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PREFACE 





This manual describes Computer Automation's Real-Time Executive 
(RTX4), a package of software modules designed to provide the 
overhead functions and scheduling services associated with 
a real-time, multi-tasking environment. 

This manual is intended to serve both as a learning tool for 
programmers, new to RTX4, and as a reference source for 
experienced users. Section 1 provides an introduction to 
RTX4 and its use. System initialization, the first operation 
performed by the program, is discussed in Section 2. The 
fundamental concepts of tasks, activities, environment, and 
semaphores are elaborated in Sections 3-6. Special facilities 
provided to RTX4 users -- system clocks and the mailbox -- are 
described in Sections 7 and 8. The appendices provide a glossary, 
descriptions of the RTX4 tables, detailed information on the 
RTX4 services, M4D12 addressing format, RTX4 exceptions, 
configuration options, and a demonstration program. 

The following Computer Automation Incorporated documents provide 
information related to the use of RTX4: 

• 0S4 System User's Manual (93460-90) 

• NAKED MINI 4 Assembler User's Manual (93500-80) 

• Input/Output Subsystem I0S4 User's Manual (93430-90) 

• NAKED MINI 4 Debugging Monitor Reference Manual (93015 90) 

• LSI 4/10, 4/30, or 4/90 Computer Reference Manual (20990*91, 
20991-91, or 20945-91, respectively! 

Contact your CAI representative for copies of these documents or any 
other CAI documents. 
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SECTION 1 

BASIC CONCEPTS OF REAL-TIME SYSTEMS 


1.1 INTRODUCTION 

Computer Automation's Real-Time Executive (RTX4) provides a real-time, multi¬ 
tasking environment for user-written applications. 

This introductory section discusses some of the concepts that are fundamental 
to real-time systems in general. Subsequent sections of this manual describe 
the use of RTX4 in particular. 


1.2 AN ANALOGY 

The following analogy of an auto repair garage and its activities, illustrateo 
in Figure 1-1, introduces the basic concepts of a real-time system and ti 
functioning of its component parts. 



Figure 1-1. Analogy of a Real-Time System 
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Assume that all mechanics change transmissions in all car's the same way. We may 
think of "replacing a transmission" as a task. It consists of a series of 
well-defined steps using a certain set of tools. At many garages there is a 
fixed price for this task, and many mechanics know how to do it. The task of 
"changing a transmission" is independent of whether anyone is doing it; that is, 
if no one anywhere is replacing a transmission, there is still a well-defined 
task called "replacing a transmission." 

There may be a place known as "Joe's Garage." It is an "environment" in which 
many mechanical tasks are performed. Joe tells his workers to perform mechanical 
tasks. In fact, he orders his task requests in a particular manner, probably 
one which maximizes his profits. Although he is in complete control of his own 
garage, he has no authority in Andy's Garage, across the street. He cannot tell 

( Andy's mechanics what to do, even though he may know as well as Andy what needs 
'o be done. There is no wall or other physical restraint between their shops, 
but the law forbids Joe to exercise authority in Andy's garage. His interaction 
with Andy's Garage is limited: he may exchange messages with Andy or his mechanic 
or even have his own car fixed there. 


If Joe tells one of his mechanics to replace a transmission, he has started an 
"activity," or an instance of the task "replacing a transmission." He may tell 
two mechanics to change two different transmissions at the same time. Then 
there would be two such activities being performed. In fact, Andy may request 
one of his mechanics to replace one at the same time, so the same task is being 
performed in two separate environments. Each instance of the task is an activity. 
Since all three mechanics can work concurrently, this situation describes a 
concurrently reentrant task. 

Suppose that replacing a transmission requires a K12 wrench. The only K12 
wrench in town is at A1's Rentals and must be reserved ahead of time. Then only 
one activity of "replacing a transmission" can be performed at one time. The 
multiple activities which Joe and Andy requested must be performed serially. 

|his may slow down their shops' throughput, but if K12 wrenches are very expensive 
(as they appear to be, since neither Joe nor Andy has one), then this might be 
the most effective way to solve the problem. 

Three terms are introducted in this analogy: 

• A task is a set of rules, instructions and resources. It is generally 
created once, perhaps occasionally updated. It can be concurrently or 
serially reusable. A task which is concurrently reusable is said to be 
reentrant. A task's reentrancy is determined by its creator (and updater), 
since he knows what resources are required by it. 

• An activity is a specific instance of performing a task. It uses three 

resources: CPU time, a task, and a context. All are allocated to the task 

when it begins. There may be many activities being performed at the same 
time, of the same or different tasks. 

• An environment is a set of resources. A task may be performed in several 
environments, but each instance or activity can use only the resources that 
exist in the environment in which it is started. Thus, environment is a 
method of T, esource allocation. 


A glossary of these and other ter^s used in this manual appears in Appendix A. 
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1.3 INTERRUPT PROCESSING 

A real-time system must respond to external events that occur asynchronously 
to processes within the computer. In this usage, "asynchronously" means 
essentially the same thing as "randomly," but the events are not truly random 
because various aspects of them are predictable (maximum interval, time window, 
relative sequence, etc.). However, their exact timings are not known, so 
real-time programs cannot afford to wait for them by looping. The accepted 
method for relating the outside world to a computer is through hardware interrupts 
The computer can perform other functions until the interrupt occurs. Interrupts 
allow the effective and efficient utilization of a computer in a real-time 
environment. 

However, current computer architecture and programming conventions are 
sequentially oriented, and interrupts make it impossible for an entire applica¬ 
tion to be seen as a single sequential process. Every time an'interrupt 
occurs the order of execution of computer instructions is changed, if only 
temporarily. 

Figure 1-2 illustrates how conceptual execution transfers when interrupts 
occur. In this example, two types of interrupts (perhaps from different 
devices) occur at two different times during the processing of the mainline 
program. Each time, execution is shifted from the mainline, to the interrupt, 
to the routine to process that particular type of interrupt, then back to the 
mainline program. 


MAINLINE INTERRUPT 

PROGRAM PROCESSING RTNEA 



Figure 1-2. Real-Time Interrupt Processing Concepts 
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The problem can be simplified by viewing the system as two or more sequential 
processes that execute concurrently. This ideal can be met by providing the 
programmer with two or more separate computers that can communicate with each 
other through status flags. Currently, this approach is economically unfeasible. 

A real-time executive can simulate the existence of multiple processors, 
allowing the programmer to treat his application as a collection of sequential 
processes, yet requiring only one CPU. Some CPU time and some memory are 
occupied with the overhead of this simulation, but the incremental costs of 
additional CPU time and memory in a single computer are relatively small. 


1.4 PROGRAMMING BY FUNCTIONS 

© One way to optimize the use of a real-time executive is by subdividing a 
program into its component functions. Each function can process when it is 
required and when the necessary hardware and other envirorimental factors are 
available. 

For example, consider a small program that reads from cards and prints them 
contents on a line printer using two buffers so that the reading ana printing 
operations can overlap in time. The asynchronous outside events in this case 
are the completion of reading a card and the completion of printing a line. 

They are asynchronous not only because of small variations in the mechanical 
devices, but because of human factors such as reloading the card hopper, 
emptying the card stacker, changing printer paper, etc. 

It is possible to solve this problem using standard sequential programming 
techniques or primitive interrupt responses. A simple alternative solution is 
shown in Figure 1-3. This solution involves two processes: Process A reads 
• cards into the buffers, and Process B prints the contents of the buffers. 

Each process consists of seven steps. The first six steps are standard RTX4 
^ system service requests consisting of two words of memory each. Step 7 is a 
jump to the start of the process so the process is repeated. Most importantly, 
the flow of processing can be followed easily; there are no conditional tests, 
no branching. 

Four system services are requested. "Read" and "print" are calls to the 
Input/Output Subsystem 1 that return only when the operation is complete. 
"Signal" and "wait" are complementary synchronization services: a process 
that waits for a condition resumes as soon as it is signalled. This service 
is known as a semaphore. Semaphores are discussed in a later section. 2 

No combination of external events can result in a card not being printed or 
being printed twice. Note how easy it is to verify that fact. Also, Process 
A and Process B could just as well be in separate computers with some shared 
memory. That is the advantage of a real-time executive: it provides concurrent 
processing without the hardware cost of multiple processors. Whenever the 
card reader is empty or both processes are waiting, other processes can use 
.the CPU time. 


1 Input/Output Subsystem I0S4 User's Manu al 

2 Section 6 
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Figure 1-3. Example Processes 
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SECTION 2 
RTX4 USAGE 


2.1 INTRODUCTION 

RTX4 is a package of software modules designed to provide the overhead functions 
and scheduling services associated with a real-time, multi-tasking environment 
, I0S4 1 is a subsystem of RTX4 which provides the user with a device-independent, 
method of I/O device management and support. 

The general organization of RTX4 and I0S4 is shown in Figure 2-1. RTX4 controls 
all aspects of priority scheduling, timing, interrupt servicing, I/O control, 
inter-task communication, and all necessary queuing functions. Modular 'instruc¬ 
tion allows the user to select only those portions of RTX4 required for ds 
particular application. 



Figure 2-1. RTX4 Organization 


1 lnput/0utput Subsystem I0S4 User's M anual 
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Some of the particular features of RTX4 are: 

• Allows the application program to be designed as a number of interrelated 
or subordinate tasks. 

• Allows the application program to schedule CPU usage by dynamically 
defining and redefining the priority and seniority levels of several 
activities in the application using RTX4 service routines. 

• Allows real-time response to external events by providing the interrupt 
instructions which transfer control to the interrupt service routines. 

• Allows the various tasks in the application to communicate between them¬ 
selves (or with RTX4) through RTX4 communication routines. 

• Provides clock services for obtaining time-of-day information and/or for 
controlling the timing of activities. 

• Allows dynamic memory management. 


2.2 RTX4 SYSTEM SOFTWARE 

The RTX4/I0S4 system software is available on floppy diskettes or on paper 
tapes. The floppy diskettes are intended for use with the 0S4 program develop¬ 
ment system. 1 The paper tapes are provided for users of the GMEGA4 program 
development system. 2 

The contents of the product diskettes and paper tapes are discussed below. 

The procedures for using each medium in its corresponding program development 
system are outlined later in this section. 3 


2.2.1 System Software Diskettes 

When RTX4 is to be used with 0S4, it is delivered as five floppy diskettes, as 
follows: 

• RTX4 Product Diskette Diskette ID Number: F41001 

CAI Part Number: 93410-01 

This diskette contains the RTX4 library file (RTX.LIB), the RTX4 demon¬ 
stration program source, object, and binary files, and a JCL file for 
assembling the demonstration program. (A listing of the demonstration 
program appears in an appendix 4 to this manual.) A Help file describes 
the diskette's contents. 


1 0S4 System User's Manual 

2 QMEGA4 System User's Manual 

3 Subsection 2.4 

4 Appendix E 




• RTX4 Macros Diskette Diskette ID Number: F42501 

CAI Part Number: 93425-01 

This diskette contains the user and development macro files. These files 
are described in Appendix H. 

• I0S4 Product Diskette Diskette ID Number: F43001 

CAI Part Number: 93430-01 

This diskette contains the I0S4 library file (IOS.LIB). 

• SFM Product Diskette Diskette ID Number: F4400I 

CAI Part Number: 93440-01 

This diskette contains the SFM library file (SFM.LIB), the SFM demonstra 
tion program source, object, and binary files, and a JCL file for assembling 
the demonstration program source file. 

•Standalone LABEL Diskette Diskette ID Number: F44101 

CAI Part Number: 93441-01 

This diskette contains the standalone 0S4 disk labeling program. This 
program can be used to label disks in SFM format. Its use is described 
in the I0S4 User's Manual. 1 



2.2.2 System Software Paper Tapes 


When RTX4 is to be used with 0MEGA4, it is delivered as a set of paper tapes. 
These tapes contain the same items as the floppy diskettes described above 
(minus Help and JCL files and the standalone labeling program) except that 
each file is provided on a separate paper tape. Each paper taps has its own 
CAI part number, as follows: 


CAI Model Number File 


93410-20 

RTXDEM0.ASM 

93410-30 

RTXDEM0.OBJ 

93410-40 

RTXDEM0.BIN 

93410-51 

RTX.LIB 

93420-60 

GEN.MAC 

93420-61 

RTX.MAC 

93420-62 

RTXD.MAC 

93420-63 

I0S.MAC 

93420-64 

I0SD.MAC 

93420-65 

SFM.MAC 

93420-66 

SFMD.MAC 

93430-51 

IOS.LIB 

93440-20 

SFMDEMO.ASM 

93440-30 

SFMDEMO.OBJ 

93440-40 

SFMDEMO.BIN 

93440-50 

SFM.LIB 


i 


m 


u 


ubsystem 


User 1 s Manual 
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2.3 RTX4 MACROS 

RTX4 provides three types of macros: macros for generating internal tables, 
macros for requesting system services, and macros which generate service 
request parameter lists. 


2.3.1 Table-Generating Macros 

RTX4 involves a number of internal tables. RTX4 generates some of these 
tables automatically; others are generated in response to macros defined by 


the user in his program. These macros 
below. 

Macro Table Generated 

TDB:A Task Descriptor Block 

INIT:A Initialization Block 


ECB:A Environment Control 

Block 

SDB:A Semaphore Definition 


MDB:A Mailbox Definition 
Block 

These macros are described in detail 
The structures of all RTX4 internal 
presented in an appendix. 1 


and the tables they generate are li 


Pu rpose of Table 

Describes the needs and attributes of 
a task. 

Provides some information about the 
environment and supplies the address 
of the first task to be executed. 

Defines user-occupied space to RTX4 
and unit assignment to I0S4. 

Defines a semaphore for controlling 
synchronization of Block tasks. 

Defines a mailbox facility for com¬ 
munication between activities. 

n subsequent sections of this manual, 
bles, including those listed above, are 


2.3.2 Service Macros 

RTX4 provides a number of services which greatly simplify programming for a 
real-time environment. To invoke one of these services, the program executes 
the corresponding service request macros as listed below. 

Macro Service Invoked 

RrBGIN Initiates an execution instance of a task; i.e., creates an 
activity. 

R:END Completes an execution instance of a task; i.e., terminates an 
activity. 


1 Appendix B 
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Macro 

Service Invoked 


R.-GPRI 

Reads an activity's priority. 


R:SPRI 

Changes an activity's priority. 


R:SATD 

Given the ASCII time and date will set in 

binary. 

R:GATD 

Reads, in binary, the time and date and converts to ASCII. 

RrCINT 

Causes the current activity to return on < 

i console interrupt. 

R:ABUF 

Allocates a buffer. 


R:RBUF 

Releases a buffer. 


R: SIG 

Signals a semaphore. 


R:WAIT 

Waits on a semaphore. 


R:ITIC 

Initiates a timer to cause a semaphore to 
specified number of Real-Time Clock ticks. 

be signalled after a 

R-.MTIC 

Modifies a previously-initiated tick clock timer request. 

R:CTIC 

Cancels a previously-initiated tick clock 

timer request. 

R:PAUS 

Drops the seniority of an activity. 


R:AWAL 

Initiates a timer to cause a semaphore to 
absolute time. 

be signalled at an 

R:IWAL 

Initiates a timer to cause a semaphore to 
specified time interval has elapsed. 

be signalled after a 

RtCWAL 

Cancels a previously-initiated wall clock 

timer request. 

R:STOD 

Sets the binary time of day. 


RrGTOD 

Reads the binary time of day. 


R:SEND 

Sends a message from one task to another. 


R:RECV 

Receives a message sent by another task. 



These macros are described in detail in subsequent sections of this manual. 

The arguments to system requests are sometimes defined as values and sometimes 
defined as pointers to lists of values. For instance, in the R:BGIN request, 
the argument is a pointer to a list of parameters needed for the R:BGIN service. 
One of those parameters is a priority descriptor which can be expressed as a 
16-bit integer. 


- 2-5 - 
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Compare this to the R:SPRI request, whose argument js^ a priority descriptor 
rather than a pointer to one. The priority descriptor may be placed in the 
second word of the service request, or in the X register when the service 
request is made. If the descriptor is to be placed in some other memory 
location, it must be referenced indirectly. 

When arguments to a service request macro must be specified in a list rather 
than directly in the macro, the programmer can call the appropriate list¬ 
generating macro. These macros are: 

BGIN:A generates an argument list for a BGIN:A request. 

MAIL:A generates an argument list for an R:SEND or R:RECV request. 

TICK:A generates an argument list for an R:ITIC, R:MTIC, or R:CTIC 

request. 

WALL:A generates an argument list for an R:AWAL, R:TWAL, or R:CWAL 
request. 

These macros are described with the corresponding request macros in subsequent 
sections of this manual. 


All service request arguments, whether specified directly in the request or in 
a list, are expressed in M4D12 format, i.e.: 

[*]Mem(X,Y) 


where: 

[*] denotes an optional asterisk immediately preceding the memory 

address to indicate indirect addressing. 

Mem is a memory address in the range 0-65535 inclusive or external. 

(X,Y) denotes indexing, which is always optional and may specify 

either X or Y or both, in either order, separated by a comma, 
and the whole enclosed in parentheses. 

This format permits a wide range of addressing modes. In simple systems, the 
direct and indirect modes may satisfy all programming needs. In more complex 
systems, a programmer may wish to place his argument pointer or value in a 
register or in his Y-scratchpad. These last two options are especially useful 
in writing reentrant tasks. The allowed addressing modes are: 

•Direct addressing to anywhere in memory 

•Indirect addressing to anywhere in memory 

•P-relative addressing to within ±4096 words of the current P register 
value 

•Pre- or post-indexing with an offset of ± 4096 
•A combination of the above 
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The following are addressing mode examples: 


ABLE 

direct reference to a label 

*BAKER 

indirect reference through a label 

CHARLY(X) 

post-indexed reference 

DELTA(Y) 

pre-indexed reference 

ECH0(X,Y) 

pre- and post-indexed reference 

*FXTRT(X,Y) 

indexed indirect reference 


See the assembler manual 1 for more information on M4D12 format. 

Macros are the preferred form for making service requests. Alternatively they 
can be made using a system trap (STRAP) instruction. The STRAP instruction in 
the first word of a service request traps to location :A4 where RTX4 proceeds 
to process the request. The first word also specifies the service being 
requested and the meaning of the second word. The second word can contain a 
value, an address, an indirect pointer, or a complex M4D12 pointer, depending 
on the service request and the contents of the first word. Together, these 
two words provide a simple, yet flexible, means of requesting services and 
providing argument values and lists. 


2.4 RTX4/I0S4 PROGRAM DEVELOPMENT 

The general procedures for developing an RTX4/I0S4 application program are 
like the procedures for developing any other type of user program: the pro¬ 
grammer designs his program, creates the appropriate symbolic text, translates 
that symbolic text to an object module or modules via an assembler or compiler, 
links the object module(s) with any required library programs, loads and 
executes the linked program, and performs any necessary debugging. 

The RTX4/I0S4 programmer can perform these processes in either the 0S4 system 
or the 0MEGA4 system. The 0S4 and 0MEGA4 user's manuals 2 provide details on 
how program development procedures are performed in those systems. This 
subsection presents some guidelines that apply to developing an RTX4/I0S4 
application program in particular. 

The 0S4 user's manual outlines a suggested procedure for creating an RTX4/I0S4 
application development system. For the reader's convenience, this discussion 
is repeated in an appendix 3 to this manual. 


1 NAKED MINI 4 Assembler User's Manual 

2 0S4 System User's Manual and 0MEGA4 ~ $ystem U s er's Manual 
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2.4.1 Designing the Program 

The first step in designing an RTX4/I0S4 application program is to divide the 
problem into a suitable number of tasks. A task, as introduced in the auto 
repair shop analogy presented earlier, 1 is a set of instructions for performing 
a particular function. For example, the two processes shown in Figure 1-3 2 
are tasks to perform the functions of reading and printing cards. 

An application system can consist of one or more tasks. There is sometimes a 
"best" way of dividing a system into tasks, but there is seldom an "only" way. 
The decision to break the card reading/printing problem into the two separate 
tasks simplified the programming problem. Solving it as a single task would 
have been unnecessarily difficult; solving it as three or more tasks would be 
O unnecessary. Figure 2-2 presents another example. 



Figure 2-2. Dividing an Application into Tasks 


1 Subsection 1.2 
2 Subsection 1.3 









CompuferAutomation - 


The rules for dividing an application into tasks cannot be spelled out, unfor¬ 
tunately. As a guideline, whenever synchronization with another process 
(internal or external) requires excessive conditional testing, create a new task 
which performs only the synchronization. This guideline may result in a 
hierarchical structure of tasks, which in many situations is an excellent 
solution. Another way of viewing this guideline is to think of functions which, 
if performed in another computer, would simplify the problem in the main 
computer. Such functions should be performed in another task. 

After dividing the problem into tasks, design the operation of each task. 


2.4.2 Coding the Program 

The elements of an RTX4/I0S4 can be coded in any order, but the program must 
include at least the following elements: 

• Initialization Block 1 

This table should be the first element of the program, as it provides 
information required by RTX4 when execution begins. It directs RTX4 to it* 
first task to be executed and to the Environment Control Block (ECB). As 
described below, the ECB describes the environment in which the program 
will run. The Initialization Block also determines the size of the System 
Freepool. As described later, 2 the Freepool is a region of memory that 
RTX4 uses for its internal tables and control blocks. To generate the 
Initialization Block, the programmer codes an INIT:A macro. 

• Task Descriptor Block(s) 3 

For each task defined in the program, the programmer generates a Task 
Descriptor Block (TDB) by coding a TDB:A macro. In general, the macro call 
should be near the code of the task it describes. While not required by 
RTX4, this approach minimizes the number of external references required. 

• Environment Control Block 4 

The Environment Control Block (ECB) describes the program's resources to 
RTX4 and unit assignment to I0S4. The ECB also contains the heads of 
several lists generated by the program. 

If the user wishes to use a nonstandard Unit Assignment Table, he must include 
the appropriate UAT:AA, UAT:EE, and UAT;ZZ macros. 5 


Subsection 5.2 
Subsection 5.3 
Subsection 3.4 
Subsection 5.4 

5 lnput/0utput Subsystem I0S4 User's Manual 
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The programmer can code his program as a single module or as multiple modules. 

A convenient modular structure for large application programs is to code each 
task, including its Task Descriptor Block (TDB:A macro), as a separate module. 
Only one module must include the Initialization Block (INT:A macro) and the 
last module to be loaded must include the Environmental Control Block. (ECB:A 
macro) at the end of that module. 

The programmer normally includes the directive: 

LOAD DEBUG4 

when coding a new RTX4/I0S4 application program. This directive causes the 
DEBUG4 system 1 to be loaded with the program, providing facilities for debugging 
the program. This directive can appear in any program module. 

Figure 2-3 illustrates the typical structure of an RTX4/I0S4 application program. 


Initialization Block (INIT:A) 


Task #1 Descriptor Block (TDB:A) 


Task #1 Code and Data 


Task #2 Descriptor Block (TDB:A) 


Task #2 Code and Data 


Task #n Descriptor Block (TDB:A) 


Task #n Code and Data 


Environment Control Block (ECB:A) 


Figure 2-3. User Program Structure 


* NAKED M INI 4 De bugginq Monitor R eference M anual 
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2.4.3 Assembling the Program 

RTX4/I0S4 application program modules can be assembled in any order. The files 
GEN.MAC, RTX.MAC, IOS.MAC, and SFM.MAC must be specified as the macro definition 
file for each assembly. 


2.4.4 Linking the Program 

The next step is to link all of the user-coded modules with the necessary library 
files. 


NOTE 


✓ 

The module containing the Environment Control Block (ECB) must be the 
last program module linked because it must contain the heads of several 
lists generated by the program. 


Following the user-coded modules, library files should be linked in th* following 
order: 

SFM.LIB Provided on the SFM product diskette or paper tape; required only 
if the program uses Standard File Manager capabilities. 

IOS.LIB Provided on the I0S4 product diskette or paper tape; required 
only if the program invokes I0S4 services. 

RTX.LIB Provided on the RTX4 product diskette or paper tape; required for 
all RTX4/I0S4 application programs. 

The program may be linked absolute or relocatable and may reside in memory at 
address :100, if two DIO boards are used :200, or greater. 


2.4.5 Loading and Executing the Program 

Once all of the program modules have been linked, the programmer can load and 
execute his program. 

When a linked RTX4/I0S4 application program is loaded, it appears in memory as 
diagrammed in Figure 2.4. The area between the end of the program and the end 
of memory is called the Environment Memory Pool 1 . This space is used for scratch 
pad and stack space requested by the program. 

If DEBUG4 is loaded with RTX4, DEBUG4 receives initial control when the user ! s 
program is executed. The user can start the program by using DEBIJG4 to transfer 
to location :80. If an exception 2 occurs, control returns automatically to 
DEBUG4. The user can access DEBUG4 at any time by transferring to location : 7E. 


1 Subsection 5.5 

2 Appendix C 






Figure 2-4. Map of All Memory 


RTX4 contains many blocks of information on a variety of lists. The programmer 
can examine these lists using the 2 command. The heads of these lists and the 
meaning of the contents of the blocks are presented on the following page. 
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Label 

Location 

Contents 

R:ECBH 

: 20 

Head of the Environment Control Block list. 

R: RDY 

: 22 

List of Activity Control Blocks currently ready for 
activity execution. R:ACT usually points to the 
first ACB on this list. 

R: ACT 

: 21 

Activity Control Block for the current activity. 

R:INTQ 

: 23 

List of Activity Control Blocks of activities which 
have been readied for execution and are awaiting 
merger into the R:RDY list the next time through the 
dispatcher. 

R: FPH 

: 25 

Head of the Freepool list of available blocks. 

R: FPT 

: 26 

Tail of the Freepool list of available blocks. 

R:CCBH 

:2B 

Head of Tick Clock Control Block list. 

R:WCBH 

:2C 

Head of Wall Clock Control Block list. 

R:T0DU 

: 30 

Time of day upper 16 bits. 

R:T0DL 

: 31 

Time of day lower 16 bits. 


The user can also examine the system trap locations which can identify the 
user's last system request. 
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SECTION 3 
TASKS 


3.1 INTRODUCTION 

A task is an ordered collection of machine instructions that perform a particular 
function. 


3.2 TASK RESOURCES 

Several resources are associated with a task, including the initial register 
context, Y-scratchpad, and the user's stack. 


3.2.1 Initial Register Context 

The contents of the A, Q, X, and possibly Y registers of the task which begins 
another task form the initial register context of the new task. The initial 
register context provides communication between the original task and the task 
to be started. It can determine the function to be performed, the location 
of data areas and.buffers, etc. If the required information does not fit into 
the registers, the registers can point to memory locations which contain the 
information. 


3.2.2 Stack 

Each execution instance of a task must have its own stack. The stack is used 
by RTX4 for several purposes, and may be used by the programmer for subroutine- 
linkages using the JSK and RSK instructions. 1 

The amount of stack space required for a task is the sum of the spaces required 
for program use and system use. The amount used by the program depends on the 
maximum depth of subroutine nesting (not the total number of subroutines). 

The amount used by the system depends on what system services are requested. 

If no services are requested, the system requires 14 words for handling inter- 
rupts (only 7 if a significantly higher maximum interrupt latency is acceptable). 
If any system services are requested, 8 more words are required. Additional 
stack locations are required for many services. The number of additional 
stack locations are listed as a part of the documentation of each service. 

Also, the use of JSK and PUSH requires 7 words of stack space. 


1 NAKED MINI 4 Assembler User's Manual 
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As illustrated in Figure 3-1, the K register points to the top of the stack 
area currently being addressed and the L register points to the lower limit of 
the stack. 


14-1 



Low Memory 


RSK and POP 
instructions 


JSKand PUSH 

instructions 


High Memory 


Figure 3-1. Stack 


3.2.3 Y-Scratchpad 

Each invocation of a task can have its own scratchpad area of any length. 

This area is called the Y-scratchpad because it is reached via the Y register. 
The size of the Y-scratchpad area is user-defined. 

Although NAKED MINI 4 Family computers have a 64-word scratchpad (the first 64 
words of memory), these words cannot be used by application programs in the 
RTX4 system. They are used by RTX4 for critical program sequences, list 
heads, and other uses that increase throughput and reduce overhead 
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Any normal scratchpad use can be performed in Y-scratchpad, including indexed 
indirect references and direct references from any memory location. The 
Y-scratchpad is allocated to a task when it begins execution. The address is 
placed in the task's Y-register as part of the initial register context The 
program refers to locations in Y-scratchpad by including the pre-indexing 
symbol (Y) on operands which are to fall into Y-scratchpad. 

Two options are available for allocating Y-scratchpad space. The task may use 
the Y-scratchpad space of the task which began it; in this case, the Y register 
value is simply passed as part of the initial register context along with the 
A, Q, and X registers. Or, the programmer may request that the Y-scratchpad 
space be allocated dynamically when the task is begun. 

In either case, the programmer is free to load the Y register with the address 
of his own Y-scratchpad region. 

It is the user's responsibility to avoid referencing locations which fall 
outside the allocated Y-scratchpad; RTX4 cannot perform any limit checking. 

The greatest volume of Y-scratchpad is required for reentrant or recursive 
programming where data areas must be allocated for each execution instance. 

All memory reference instructions can refer to Y-scratchpad, including single- 
word memory reference instructions (64-word range), system request parameters 
(4096-word range), and double-word memory reference instructions (65,536-word 
range). 

Figure 3-? illustrates Y-scratchpad allocation and how it is accessed end used 
in a task. 



Figure 3-2. Y-Scratchpad Allocation and Access 
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3.3 SERIAL/REENTRANT TASKS 

A task may be serial or reentrant in its use. If a task is serial, one activity 
(execution) of the task must be completed before the next activity can begin. 

A reentrant task can support several activities executing concurrently. 

A reentrant program significantly reduces memory size for some applications. 

For example, consider a data entry system consisting of four CRT terminals 
connected to one computer and a disk. An operator sits at each terminal 
entering data from questionnaire forms into the computer. 

One approach to building this system would be to create four copies of the 
data entry program, as illustrated in Figure 3-3. Such a solution reduces 
^ development time and speeds execution time. 



Figure 3-3. Serial Approach 


The reentrant approach, illustrated in Figure 3-4, requires a slightly longer 
development time and may run slightly slower, but the resulting system uses 
much less memory and is easier to maintain and expand. 
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Figure 3- ! -4. Reentrant Approach 


3.3.1 Serial Tasks 

In a serial task, resource allocation is simple, but several options are 
available. The simplest method, with the lowest CPU overhead, is to allocate 
space for the stack along with the task and tell the system where it is RTX4 
then faces no dynamic allocation problems. This method also protects that 
memory space from being available for other uses when the task is inactive. 
Alternatively, the programmer may ask RTX4 to allocate the stack and Y-scratchpad 
space dynamically when the task begins. He must supply the lengths of each, 
but RTX4 determines their locations. In either case, when the task begins, 
the Y, K, and L registers are set to point to the Y-scratchpad and stack. 


3.3.2 Reentrant Tasks 

The terms "orocedure" and "data" are fundamental to reentrant programming. 
Essentially, the procedure is the unchanging part of the reentrant task and 
the data is the variable portion. 

A procedure includes all portions of a program which do not change during program 
execution. It includes all items such as machine instructions, literals, data 
constants, and fixed address pointers which determine the process to be performed 
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Data in the reentrant task refers to all items such as variables, temporary 
cells, stacks, and buffers which may change during program execution. It 
includes all program memory locations which do not qualify as procedure. 

These terms are the basis of the following concepts of reentrant programming: 

• Procedure and data are treated separately. 

• Each activity of the reentrant task has its own allocated region for 
data. 

• All activities of the reentrant task share the same procedure. 

Suppose that the example data entry system presented earlier 1 requires 10K 
words of procedure and 4K words of data for each data entry station (CRT). 

The serial approach requires 61K words of memory: 

5K* RTX4/I0S4 

40K Procedures (4*10K) 

16K Data (4*4K) 

The reentrant approach requires only 33K words of memory: 

5K* RTX4/I0S4 

10K Procedure 

16K Data 

^Approximate figure 

Such savings are common when reentrant programming is appropriate. 

Initial resource allocation for a reentrant task has few options. The stack 
must be allocated dynamically by RTX4. Y-scratchpad also must be allocated 
dynamically if it is required. Additionally, the following rules for writing 
the task must be followed to ensure reentrancy: 

• The Y-scratchpad address (the initial contents of the Y register) must be 
kept in a register at all times. 

•All references to variables and temporary cells must be relative to a 
register, usually the Y register. 

•All subroutine linkages must be made using JSK and RSK. Variable parameter 
passing must be through the registers. 

All of the above factors concerning the task must be considered in writing the 
code. After writing the task, the programmer summarizes his decisions for 
RTX4 by creating a Task Descriptor Block, described in the following subsection. 2 


Subsection 3.3 
Subsection 3.4 
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3.3.3 Memory Requirement Guide 

Typiecal memory sizes to accommodate component parts are listed below: 


IOS ... 

. .. 3K 

SFM 

... 3.2K 

RTX ... 

... 2.3K 


3.4 TASK DESCRIPTOR BLOCK 



A Task Descriptor Block (TDB) is used to describe the needs and attributes of 
task to RTX4. If the Y-scratchpad and stack areas are to be allocated by 
RTX4, they are identified in the TDB. Each Task Descriptor Block is generated 
by the TDB:A macro. 


3.4.1 TDB:A Macro 


The TDB:A macro can occur anywhere in the task, but is usually placed at the 
beginning. TDB:A has five required parameters: label of the TDB, starting 
address of the task, address of stack space, and amount of stack space. The 
macro also has two optional parameters: flags and concurrent usage. The 
formats of the TDB:A macro are: 



TDB: A 
TDB: A 
TDB: A 

where: 





1 abel , start , yscratch ,s tackad , stackamt 
label , start , yscratch , stackad , stackamt , flags 
label , start , yscratch , stackad , stackamt , flags , usag e 


label Label to be assigned to start of TDB. 
start Starting address of task. 

yscratch Amount of Y-scratchpad to be used by the task. 

If zero, the Y register of the calling task is 
used. Must be zero (or omitted) for a serial task. 


stackad Address of preallocated stack. If zero, stack 
space is allocated by RTX4. Must be zero (or 
omitted) for a reentrant task. 

stackamt Amount of stack space used by the task 

flags None currently defined. 


usage Maximum number of concurrent activities of this task. 
DEFAULT = 1 



To omit a parameter, enter two consecutive commas (,,). 

In RTX4, each activity must have a stack for storing return addresses for a 
JSK. The stack is also used by the system to save the context of an activity 
that is making a system request or is interrupted. Also, some service routines 
use this area for storage of return addresses. 


- 3-7 - 
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The user must specify the amount of stack space required. He can allocate the 
stack space himself in his program and he can supply the address in the TDB:A 
stackad parameter. As an alternative, the user may allow RTX4 to allocate the 
stack dynamically by specifying zero in the stackad parameter. In either 
case, he must specify the amount of stack space required through the TDB:A 
stackamt parameter. However the stack space is allocated, when the activity 
begins, the K register marks the top of the stack area currently being addressed 
and the L register marks the lower limit of the stack. 


The amount of stack space needed depends on the use of the stack by both the 
user's program and the system. Space is calculated as follows: 


C 


7 words To save the context of an activity when an interrupt occurs. 

8 words To save the context of an activity when a system service 

request is made, and call the appropriate service routine. 

n words The maximum used by any called system service routine (amount 
given in the description of each service). 

7 words To prevent a hardware stack exception trap after a PUSH or J$K 


* 


n words For the user program (e.g., subroutine calls). 

System service routines are executed as part of the activity requesting the 
service, and they use the stack of the requesting activity. Therefore, if an 
interrupt occurs during the execution of a service routine, 15 words of context 
are on the stack. 


A stack exception trap occurs when, after a PUSH or JSK has been executed, 
less than seven words of stack space remain. This situation can occur when a 
system service routine is interrupted, because both the current context and 
the user's context at the time of the request would be on the activity stack, 
lhe stack exception trap processing checks for this special case and resumes 
processing if it is found. This extra processing can cause excess interrupt 
latency. An additional seven words of stack space prevents this problem. 


3.4.2 Examples 

The following TDB:A macro creates a Task Descriptor Block for a serial task: 
TDB:A SBLOCK,START,,TSTACK,70 

A 70-word stack, starting at location TSTACK, is allocated for the task. 
Y-scratchpad space is determined by the calling task. 

A reentrant example: 

TDB:A RBL0CK,RBEG,100,,90,,3 

This macro generates a TDB for a reentrant task which may have up to three 
concurrent activities. Each is allowed 100 words of Y-scratchpad space, 
allocated by R T X4. A 90-word stack is allocated for each activity. 


3-8 - 
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SECTION 4 
ACTIVITIES 


4.1 INTRODUCTION 

An activity is an execution instance of a task. Each time a task begins , a 
new activity is created. When RTX4 is viewed as simulating multiple processors, 
each activity is equivalent to a separate CPU. The activity is the unit to 
which the real CPU's time is allocated. Only one activity can exist at a time 
for a serial task, as illustrated in Figure 4-1. 



Figure 4-1. Task with One Activity 

A reentrant task can have several concurrent activities, as illustrated in 
Figure 4-2. 



Figure 4-2, Task with Multiple Activities 













4.2 ACTIVITY OPERATION 



RTX4 creates an Activity Control Block when an activity is begun. The infor¬ 
mation derived from the Task Descriptor Block is placed in an available block 
obtained from the System Freepool . 1 


An Activity Control Block is always in a list, except for very short times 
while moving from one list to another. The nature of each list determines the 
state of activities that are in it. An activity must be in the system ready-to-run 
list (R:RDY) before it can execute. When an activity is waiting for an event 
to occur, it is usually in a semaphore wait list . 2 

The order in which activities are dispatched from the ready-to-run list , 

0 (R:RDY) is determined by priority. ' 

Priority is a means of assigning relative importance to activities. An activity 
of higher priority is always granted a requested resource before a lower 
priority activity. In RTX4 the priority of the first task is assigned by the 
INIT:A macro . 3 For other tasks, priority is established when the activity is 
begun. 

Among activities of different priorities, the highest priority activity is 
always dispatched. If more than one activity is at the highest priority in 
the ready-to-run list, the first one inserted in the list is alw ays dispatched. 

This dispatching algorithm is called "pure priority scheduling.^ It has some 
important ramifications in writing systems using RTX4. 

It is possible to write systems in which some activities never receive CPU 
time. A simple example of this is a system consisting of two tasks; one task 
is executed at high priority and consists of one instruction, a jump to itself. 

The second task is executed at low priority and is intended to accomplish some 
useful function. In RTX4, after the first task begins, the second task never 
Q) receives any CPU time. A second example is two activities that have the same 

priority. The first one to enter the ready-to-run list always executes first, , 
and the second one only receives CPU time if the first makes a system call which 
suspends its activity. 1 

RTX4 provides means for changing the task priority during activity execution , 4 
so that other tasks may then supersede the first task in priority. It also 
provides a means for round-robin scheduling . 5 



Subsection 5.3 
Section 6 
3 Topic 5.2.1 
4 Topic 4.3.3 
Subsection 7.4 
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Activities may be rescheduled when the following system services are called: 


R:BGIN 

Begin task (one extra block temporarily) 


R: END 

End task 


R:SPRI 

Set priority 


R: SIG 

Signal semaphore 


R:WAIT 

Wait on semaphore 


K: AIM 

Send message 


R:RECV 

Receive message 


R:ITIC 

Signal semaphore at a given time interval 
of time interval) 

(for duration 

R:MTIC 

Modify tick clock timer request 


RrCTIC 

Cancel tick clock timer request 


R:AWAL 

Signal semaphore at an absolute wall clock time 

R:IWAL 

Signal semaphore after a given time interval has elapsed 

R: CWAL 

Cancel wall clock timer request 


R:ABUF 

Allocate buffer 


R:RBUF 

Release buffer 


R:CINT 

Return to calling activity when console interrupt is 
pushed 

R:PAUS 

Drop seniority of the first activity of a 

given priority 


4.3 ACTIVITY CONTROL 

The programmer uses the R:BGIN macro to start task processing (i.e., to create 
an activity), the R:END macro to end a task, the R:GPRI and R:SPRI macros to 
get and set priorities during task processing. 
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4.3.1 R:BGIN Service 

An activity is created by the system service R:BGIN. R:BGIN allocates stack 
space as specified in the Task Descriptor Block and creates an Activity Control 
Block for the activity which is then placed in the ready-to-run list. The registe 
contents of the task that issues the request are the initial register contents of 
the activity created. This service requires 12 words of stack space. The format 
of the R:BGIN macro is: 

R:BGIN arg 

where: arg M4D12 pointer to the argument list. 

The argument list can be generated via the BGIN:A macro, which has the format: 
BGIN:A arg , tdb , prdesc 

where: arg Must match the R:BGIN argument. 

tdb Label of the Task Descriptor Block as 

specified in the TDB:A macro. 

prdesc Priority descriptor defining the task's priority. 

The priority descriptor ijs the effective address ( not the contents of the effec¬ 
tive address) of any valid M4D12 expression. The high-order bit of the priori ty 
descriptor determines whether the value is an absolute (bit 15=0) or a relative 
(bit 15=1) priority. If it is relative bit 14 determines whether to increase 
(bit 14=0) or decrease (bit 14=1) using the remaining value. 

Only positive priorities are allowed in RTX4. A relative offset that results in 
a negative priority causes undefined results. RTX4 allows user priorities from 1 
to :3FFF Higher priorities are reserved for system use. 


4.3,2 R:END Service 

When an activity completes its processing, resources are returned to the system 
by the R:END service routine. This routine terminates the activity by returning 
the Activity Control Block space to the System Freepool and any RTX4 allocated 
stack area to the Environment Memory Pool. This is the last request of any 
activity. The R:END macro has no parameters. This service requires 9 words of 
stack space. 
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4.3.3 R:GPRI and R:SPRI Services 

The R:GPRI macro returns the activity's priority in the A Register. The macro 
has no parameters. Three (3) words of stack space are required for this service. 

The R:SPRI request allows an activity to alter its priority. The new priority 
can be absolute or it can be set relative to the current priority. This 
service requires 10 words of stack space. The request format is: 


R:SPRI 
where: 

The fol1owing 


prdesc 

prdesc Priority descriptor expression; an M4D12 expression 
whose effective address ijs the priority descriptor. 

is an example of using the priority service macros: 


R:SPRI 
R:SPRI 
R:SPRT 


100 

100 + :8000 

-100 


Set priority to 100 
Increase priority by 100 
Decrease priority by 100 

value always relative) 


,\ \ \ w ClM rvicw 

ttw activity making the R.-CINT request returns when the console interrupt is 
pressed. If the console interrupt is never pressed, the activity never returns. 
Only one activity at a time can invoke this service. If this service is not 
requested, a console interrupt is ignored. 


This service requires 5 words of stack space. The macro has no parameters. 
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4.4 ACTIVITY CONTEXT 

A context is associated with each activity. The activity context is a set of 
task resources that is saved each time the execution of the task (the activity) 
must be suspended. The context is restored to the saved state when the task 
is resumed. The context of an activity includes the following items: 

• An Activity Control Block (ACB) that contains pointers to the rest of the 
context. 

• A priority that determines how real CPU time is allocated to activities. 

• The task of which the activity is an execution instance. 

• The environment 1 from which the activity's non-CPU resources are to be 
drawn. 

• The stack allocated to the activity when the task was begun. 

• The Y-scratchpad allocated to the activity when the task was begun. 

• When the activity is executing, the contents of the registers are con¬ 
sidered part of its context. When the activity is not executing, the 
register contents reside on the activity's stack. 

The context of an activity provides the information necessary to simulate a 
dedicated CPU. Whenever an activity is dispatched (i.e., allowed to execute), 
RTX4 must be sure that the activity's environment is intact, then restore Hs 
register contents, including the P register, so that execution can continue. 
Whenever an interrupt occurs, RTX4 must save the activity's register contents 
on its stack so that they are not lost by further processing. 


Section 5 



m 
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SECTION 5 

SYSTEM INITIALIZATION AND ENVIRONMENT DEFINITION 


5.1 INTRODUCTION 

RTX4 execution starts at location :80, from which RTX4 goes to its initializa¬ 
tion routine. The initialization routine needs certain information which is 
provided in the Initialization Block. 


5.2 INITIALIZATION BLOCK 

The Initialization Block is generated by the INIT:A macro. When system initia¬ 
lization is complete, the user task specified in the call is started. Only ore 
activity can be initiated by the INITA routine. R:INIT must be declared as an 
entry point (NAM) by the user's program. 


| 5.2.1 INIT:A Macro 


The format of the INIT:A macro is: 

INIT:A a,q,x,y,ecb,tdb, pri , amtfree , adrfree , topmem 


where: 


a,s,x,y 

ecb 

tdb 

Ell 

amtfree 

adrfree 

topmem 


Initial values of the A, Q, X, and Y registers for 
initial user's task 

Label of the Environment Control Block 

Label of the Task Descriptor Block for initial 
user's task 

Activity priority for initial user’s task 
Amount of System Freepool (words) (optional) 
Address of the freepool (optional) 

Upper limit of memory available to RTX4 (optional) 


Any addresses (adrfree, ecb, tdb, topmem) which are defined outside the module 
containing the INIT:A must be declared external. 

When an optional parameter is omitted, a comma must be inserted to hold the 
position of later parameters. 


If the upper limit of memory available (topmem parameter) is omitted, RTX4 
searches for the end of memory and uses all that is available. This parameter 
is useful primarily for checkout; in this case, its use is necessary to prevent 




RTX4 from allocating space for the Environment Memory Pool from the entire 
available memory. At checkout, other programs may be in upper memory. The 
parameter may be used also to check out an application on a computer that has 
more memory than the computer on which the program is to run for production. 



5.2.2 Example 


o 


NAM 

R:INIT 

INITIALIZATION BLOCK NAME 

EXTR 

ECBNAME 

ENVIRONMENT CONTROL BLOCK 

EXTR 

TDBNAME 

TASK CONTROL BLOCK NAME 

INIT: A 

0,0,0,0,ECBNAME,TDBNAME,700,100,0 

END 




In this example: 

•The A, Q, X, and Y registers are initially set to zero. 

•The ECB and TDB names are in another module and are declared external. 
•The activity priority is 700. 

•The Freepool of 100 words is to be allocated by RTX4. 

• RTX can use all available memory. 


5.3 SYSTEM FREEPOOL 

The System Freepool is a user-specified area that provides small buffers for 
RTX4 functions. The Freepool contains dynamically allocated areas such as 
Activity Control Blocks as well as areas used as temporary storage cells. It 
is organized as a linked list that can be dumped by DEBUG4 1 to provide a 
history of system execution. 

The System Freepool consists of a region of memory provided to RTX4 at assem¬ 
bly time. The user must specify the amount of Freepool space he is allocating 
and may either allocate it himself or let the INIT:A macro allocate it. 




During initialization, RTX4 breaks up the Freepool region into many fixed- 
length Freepool blocks. These blocks are used by RTX4 services to contain 
dynamically allocated blocks such as Activity Control and Clock Control blocks. 
Blocks are also used for short periods of time to contain temporary cells and 
for longer periods of time to contain information which controls a system 
resource. 

The System Freepool is organized as a linked list to speed system processing 
and debugging. RTX4 keeps track of both the head and tail of the list. 

Blocks for RTX4 services are removed from the head of the list and are returned 
to either the head or tail of the list. Short-lived temporary cell blocks are 
returned to the head of the list to be recycled immediately. Blocks used for 
control information, such as Activity Control Blocks, are returned to the tail 
to provide a history of system and application program activity to aid in 
debugging. Freepool organization is illustrated in Figure 5-1. 


rv 



* NAKED MINI 4 Debugging Monitor Reference Manual 


Kevised 
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Table 5-1. Freepool Blocks for RTX4 System Services 


Service 


Blocks A'l located (+) 
or Deallocated (-) 


R:BGIN 
R: END 
R: GPRI 

© R;SPRI 

R: SIG 

R:WAIT 

R:SEND 

R:RECV 

R:ITIC 

R:MTIC 


Begin task (one extra block temporarily) 

End task 

Get priority 

Set priority 

Signal semaphore 

Wait on semaphore 

Send message 

Receive message 

Signal semaphore at a given time interval 
(for duration of time interval) 

Modify tick clock timer request 


R:CTIC Cancel tick clock timer request 



R: AWAL 
R:IWAL 


Signal semaphore at an absolute wall clock time 

Signal semaphore after a given time 
interval has elapsed 


R:CWAL 

Cancel wall clock timer request 

R:ABUF 

Allocate buffer 

RrRBUF 

Release buffer 

R:CINT 

Return to calling activity when console 
interrupt is pushed 

R:PAUS 

Drop seniority of the first acitivity of 
a given priority 

R:SATD 

Set ASCII time and date 

R:GATD 

Read ASCII time and date 

R:STOD 

Set time of day 

R:GT0D 

Read time of day 


+ 1 (+ 2 ) 
-1 
0 
0 
0 
0 
0 
0 
+1 


0 

-1 (success) 
0 (fail) 

+1 

+1 


1 (success) 
0 (fail) 

0 

0 

0 

0 

0 

0 

0 


0 
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Figure 5-1. Functional Organization of System Freepool 


5.3.1 Freepool Size 

The Freepool is grouped into blocks of twelve words each. At least two of 
these blocks must be reserved. 

The space needed for the System Freepool must be determined by the user. 

Freepool size is determined primarily by the amount required by each RTX4 
system service request used in the application program. During debugging, a 
larger area may be desirable for system history. 

Table 5-1 lists the number of contiguous blocks required for each of the 
system requests. This number provides a rough guide to selecting an initial 
Freepool size. Then, determine how much additional space is required for a 
complete history during debugging. RTX4 keeps track of the maximum number of 
blocks used during an execution in location FPMAX:. This number helps determine 
final Freepool size. While asynchronous events and random chance may require 
more Freepool blocks for any one execution, the programmer can get a good 
estimate from several runs and compensate for possible increases by providing 
a somewhat larger Freepool area. 

- 5-3 - 
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5.3.2 The Freepool and Debugging 

If the user provides a much larger Freepool during debugging than he expects 
to use during production, a dump of the Freepool list can provide a significant 
history of what has happened in the system. The last item in the list is the 
most recently returned block, excluding those needed by the tick clock service. 
Preceding blocks mark historical events until the first one or two blocks are 
reached; at this point the history is lost. The head of the Freepool list is 
at location R:FPH; location R:FPT points to the last block on the list. 

Computer Automation recommends that the initial development of an RTX4 applica¬ 
tion be performed on a computer system with more memory than the final program 
is expected to use. This procedure allows the programmer to ignore memory 
allocation problems such as Freepool while getting his application to work. 
Further, the history provided by the Freepool list is longer and more helpful 
for debugging. 

Thus, the Freepool size may vary from debugging through running with test data 
to production runs. The original estimate based on Table 5-1 can be doubled 
for debugging to provide a complete history. Then, when the debugged program 
is run with test data several times, actual Freepool usage can be determined 
by examining location FPMAX:, keeping in mind that usage may vary from one run 
to the next. For production runs, the actual usage should be augmented by 
several words to provide a safety factor. 

To summarize, the steps to determine Freepool size are: 

1) Estimate size using Table 5-1. 

2) Double or triple the estimate for debugging. 

3) Exercise checked out program with test data. 

4) Check actual Freepool usage by examining FPMAX: after running the 
program. 

5) Add a safety factor to actual usage for production usage. 
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5.4 ENVIRONMENT CONTROL BLOCK 

The Environment Control Block helps define user-occupied space to RTX4 and unit 
assignment to I0S4. The Environment Control Block is generated by the ECB:A 
macro. The only value that the user must provide is a pointer to the Unit 
Assignment Table; RTX4 automatically supplies all other required values to the 
ECB. 


5.4.1 ECB:A Macro 

The ECB:A macro call must be placed at the end of the last user module. The 
format of the ECB:A macro is: 

O ECB: A label , uat 

where: label Label to be assigned to start of ECB; 

referenced in the intialization call to 
RTX4 (INIT:A). 

uat Address of the Unit Assignment Table. 

The Unit Assignment Table (UAT) must be constructed by the user. 1 If the INIT:A 
macro is not in the same module as the ECB:A macro, the user must declare "label" 
an entry point (NAM). If the Unit Assignment Table is not in the same module as 
the ECB:A macro, the user must declare "uat" to be external (EXTR). If the I/O 
subsystem is not required, the UAT address is zero. 


5.4.2 Example 


NAM 
EXTR 
ECB: A 
END 


ECB 1 
UAT 

ECB1,UAT 


This sequence generates an Environment Control Block starting at location ECB1. 
This ECB contains a pointer to the Unit Assignment Table located at UAT. 


5.4.3 EDXVT:A Macro 

The EDXVT:A macro is used to specify user written exceptions processor. A user 
may specify an exception processor for any exception needed for one and all 
exceptions. The user must make a call to the EDXVT:A macro for each exception 
to be processed All calls to the EDXVT:A macro must follow the call to ECB A 
macro. 

Refer to Appendix C for a list of RTX4 Exceptions. 


1 Input/Output Subsystem (I0S4) User's Manual 


m 
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EDXVT:A label , vector , address 

where: label Label to be assigned at start of ECB 

vector Name of exception vector, (refer to Appendix C). 

address The address of the user's exception processor. 

When control is received at the user's exception processor, the RTX4 has already 
executed a JSK and a PUSH giving the user registers and the return address, after 
the instruction which caused the trap. The two exceptions to this rule are listed 
below: 

A. The first occurs if it was an unimplemented instruction trap, then 

RTX4 will transfer control to the emulator, if the user has previously 
linked the emulator with his application. * 

B. If it was a stack exception, then the JSK and PUSH instructions are 
not performed. Instead the user may specify a four word block where 
the A, Q, X, and Y registers can be saved. The block may be specified 
by calling the EDXVT:A macro using the XV:STK$V vector. 


5.5 ENVIRONMENT MEMORY POOL 

The Environment Memory Pool is the space used for Y-scratchpads and stacks and 
user-requested buffers. This space is whatever remains between the end of the. 
user's program and the end of memory. The user is responsible for ensuring 
that the Environment Memory Pool is large enough provide for all al locations 
required of it. Allocation is performed by a standard first-fit algorithm, so 
some fragmentation may result, increasing the size requirement. 

RTX4 does not use any space in the Environment Memory Pool for its own tables 
or control blocks. Space for these items is obtained from the System Freepool. 


5.6 BUFFER ALLOCATION 

RTX4 provides the R:ABUF and R:RBUF services for allocating and then releasing 
buffer space. 
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5.6.1 R:ABUF Service 

The RrABUF macro allocates a buffer for use by the program. The argument to 
this macro specifies the number of words to be allocated. This service requires 
10 words of stack space. The format is: 

RrABUF amount 

where: amount Number of words to be allocated. 

The number of words which can be allocated via RrABUF is limited only by the 
amount of contiguous space available in the Environment Memory Pool at the 
time the request is made. 

The system returns the address of the allocated buffer in the X register. 

For example: 

RrABUF 256 

This request allocates a 256-word buffer. The buffer address is returned in 
register X. 


5.6.2 R:RBUF Service 


When the program has completed its work with a buffer allocated via a previous 
RrABUF request, it can return that space to the system by executing an R:RBUF 
macro. This service requires 10 words of stack space. The format is; 


RrRBUF address 

^ where: address Address of the buffer to be returned. 

The argument to this macro is the address of the buffer. Since this address 
is not known until execution, the argument typically specifies register- 
relative addressing mode. 

For example: 

RrRBUF 0(X) 

This request releases previously-allocated buffer space. It assumes that the 
buffer address is still in register X. 


cup 
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SECTION 6 
SEMAPHORES 


6.1 INTRODUCTION 

RTX4 provides system services that allow the efficient programming of inter¬ 
task cooperation to synchronize the execution of tasks so that they occur in a 
specific time relationship to one another. The facilities that are provided 
are based on a concept called the "semaphore." Sempahores were first formalized 
in 1965 by E. W. Dijkstra. 1 

This section introduces semaphores by first discussing some alternative methods 
of intertask cooperation. For further information on the subject of semaphores, 
a book by Brinch-Hansen is recommended. 2 


6.2 ALTERNATIVE APPROACHES TO INTERTASK COOPERATION 

Intertask cooperation may be used for passing data (intertask communication) 
or may be used simply because one task must be accomplished before another 
(intertask coordination). Intertask coordination includes "producer-consumer" 
problems and "resource sharing" problems. 


6.2.1 Producer-Consumer Cooperation 

Figure 6-1 illustrates an example of a producer-consumer problem: task A 
fills a buffer and task B wants to know when it is full. One solution is to 
designate a location (call it CELL) as a flag. Task A sets the flag to a one 
when the buffer is full. Task B tests the flag and knows that the buffer is 
full when the value of the flag becomes a one. The operation for task A is 
straightforward: fill the buffer, then set CELL to a one. Task 6 can process 
the buffer when CELL is found to be a one, but has no function while CELL is 
zero. One choice would be to test the CELL again immediately. This approach 
results in a very tight loop which has several bad side effects. If the task 
dispatching scheme is pure priority, task B uses all available CPU time so 
that task A never is able to change the value of CELL. In a time-slicing 
system, task B uses unnecessary amounts of time, perhaps keeping task A from 
filling the buffer as fast as it might. In terms of reasonable system throughput, 
the solution is unacceptable in either case. 


X E. W. Dijkstra, "Cooperating Sequential Processes" (1965) 

2 Per Brinch-Hansen, Operating System Principles (Prentice-Hall 1973) 
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TASK A 


TASK B 





Figure 6-1. Producer-Consumer Problem Non-Semaphore Solution 


An improvement would be for task B to suspend itself for a while, using the 
system clock, between each time it tests CELL. This solution reduces the load 
on the system and allows task A to complete filling the buffer in a finite 
time. Its main disadvantage is that task B may not find out that the buffer 
^ is full as soon as it should. There is a definite tradeoff: the less load 
task B places on the CPU (the longer the wait) the longer task B may be unin¬ 
formed that the buffer is full. 

This problem may be reduced if task A can cancel task B's wait on the clock, 
but there are several timing bugs associated with this operation. Suppose 
task A cancels the wait while task B is not waiting, for instance. Also, the 
system overhead and complexity is high (several waits on the clock and one 
cancel request). In some systems, task A sends a message to task B through a 
system message facility. Other systems require task A to “create" task B each 
time the buffer becomes full. Both solutions require more overhead than is 
needed to solve this problem. 

The semaphore provides a simple solution to the producer-consumer problem. 1 


1 


1 Topic 6.3.1 
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6.2.2 Resource Sharing 

The other general problem of concurrent task execution is resource sharing. 
Suppose several tasks wish to use a single resource, such as a disk. Although 
RTX4 can make it appear that several tasks are executing asynchronously in the 
computer, the disk must be used entirely sequentially, so a method must be 
devised to share the disk. 

A location such as CELL may be used as in the previous example, but the same 
problems arise. The value of CELL may initially be one, meaning the resource 
is available. The first task that arrives examines the value of CELL. Since 
it is one, the task stores a zero in CELL and proceeds to use the resource. 
Since a zero value in CELL means that the resource is not available, tasks 
that come later can tell whether they may use it. Ignore for the moment their 
problems with doing anything reasonable when they find the resource unavailable 
When the first task finishes using the disk, it must store a one in CELL, 
indicating the resource is now available. If only one task is waiting to use 
the resource, it may proceed. If more than one task is waiting, a new problem 
arises: which gets the resource next? If the waiting tasks are suspending 
themselves on the system clock, the choice of next task is made randomly: the 
task that completes a wait next (or a new task which arrives after all trie 
rest) will get the resource. This is not fair. More fair would be first in, 
first out order. More preferable might be priority order. 

Again, this problem is solved simply and with low system overhead using 
semaphores. 1 


6.3 SEMAPHORE SOLUTIONS TO INTERTASK COOPERATION PROBLEMS 

Semaphore operation is described in a later subsection. 2 Briefly, a semaphore 
has two operations, signal and wait. The effect of the two operations depends 
on the current state of the semaphore, which is determined by its initial 
condition and previously performed operations. 

The wait operation of a semaphore consists of determining whether the sema¬ 
phore has been signalled. If it has been, the waiting activity proceeds 
without delay and the signal is cancelled. If the semaphore has not been 
signalled, the waiting activity is removed from the ready--to-run list and 
entered into a wait list associated with the semaphore. The signal operation 
first determines whether any activities are in the wait list associated with 
the semaphore. If so, one activity is removed from the list and placed in the 
ready-to-run list. If not, the state of the semaphore changes to indicate 
that the semaphore has been signalled. 

Semaphores provide efficient solutions to the "producer-consumer" and "resource 
sharing" problems described previously. 3 


1 Topic 6.3.2 

2 $ubsection 6.5 

3 Subsection 6.2 
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6.3.1 Producer-Consumer Problems 

In the producer-consumer problem, the initial value of the semaphore is zero, 
which indicates that it has not been signalled and that no activity is waiting 
on it. The solution is simple: the consumer "waits" on the semaphore when he 
wishes to know when the buffer is full; the producer "signals" the semaphore 
when the buffer is full. The coding is simple: each task requests a single 
system service, then continues processing. It does not matter which activity 
makes its system request first; synchronization occurs in any case. 



© 


The objections to the previous solutions do not apply to the semaphore solution. 
Each activity executes asynchronously. If the consumer waits for the buffer 
before it is available, it does not waste CPU time; it is simply removed from 
the ready-to-run list. Yet once the buffer is full and the producer signals 
the semaphore, the consumer becomes ready to run immediately. There is no 
delay, and the system overhead of using a semaphore is minimal. 


6.3.2 Resource Sharing Problems 


The resource sharing problem is solved similarly. The initial value of the 
semaphore is one, indicating that the resource is initially available. Each 
activity must wait on the semaphore before using the resource and signal the 
semaphore after using it. The first activity to wait on the semaphore proceeds 
to execute immediately because the resource is available. Any activities that 
request the resource later find the semaphore "unsignalled" and are removed 
from,the ready-to-run list. When the first activity finishes using the resource, 
it signals the semaphore, allowing one and only one activity to use the resource 
next. 


Again, using the semaphore has overcome the objections to the previously 
described solution. It has the same advantages as in the producer-consumer 
problem, plus an additional benefit: all of the waiting activities are in a 
single list, allowing great flexibility in choosing which one executes next. 

In most cases priority determines which waiting activity executes next. In 
some cases other criteria may be used. For instance, shortest seek time might 
be used if the semaphore is controlling a disk. 

A further advantage of the semaphore is that if more than one of a particular 
type of resource is available (such as a limited set of buffers), the initial 
value of the semaphore can be changed to handle more than one. For instance, 
if two buffers are available, the initial value of the semaphore is two. The 
first two activities which request a buffer get them; all later requesting 
activities are suspended until one of the first two activities signals the 
semaphore. 






Computer Automation • 


6.4 SEMAPHORE DEFINITION BLOCK 

A Semaphore Definition Block can be provided by the user to control the synchro¬ 
nization of tasks. This block is generated using the SDB:A macro. 


6.4.1 SDB:A Macro 

The SDB:A macro establishes the location and initial value of a semaphore in a 
user's program. The macro's format is: 

SDB:A label . value 

where: label Address label of the semaphore. 

value Initial value of the semaphore. 

6.4.2 Example 

The following macro call generates a Semaphore Definition Block: 

SDB:A SEMA1.0 

The address label of the semaphore is defined as SEMA1 and the initial alue 
of the semaphore is defined as 0. 


6.5 SEMAPHORE OPERATION 

In RTX4 a semaphore consists of only one word. That word is used for a counter 
and a wait list head. The state of the semaphore is determined entirely by 
the value of this word. 

In its initial condition, the wait list is always empty, and the counter may 
be either zero or positive, depending on the use of the semaphore (zero for 
producer-consumer problems, positive for resource sharing problems). The 
effects of the two operations on a semaphore are: 

WAIT: If the counter is greater than zero, the counter is decremented 
and the waiting activity is re-scheduled according to priority, l'f the 
counter is zero, the waiting activity is removed from the ready-to-run 
list and placed in the semaphore wait list. 

SIGNAL: If any activities are in the semaphore wait list, one of them is 
removed and placed in the ready-to-run list. If no activities are waiting, 
the counter is incremented. 

Figure 6-2 illustrates the flow of these operations. 
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Figure 6-2. Flow of Semaphore Operations 


me length of the wait list is the number of unsignalled wait requests, and 
the counter indicates the number of unwaited signal requests. Thus, the 
counter is never negative. 

RTX4 contains a special form of semaphore. The main feature of an RTX4 sema¬ 
phore is that an exception occurs if the counter reaches 127. An RTX4 semaphore 
consists of one word only that is used for both the counter and wait list 
head. If the value of the word lies in the range 0 through 255, then it is 
the semaphore counter value. If the value is larger than 255, it is the head 
of the list of Activity Control Blocks that are waiting on the semaphore. 

Thus, the state of an RTX4 semaphore is determined entirely by the value of 
its one word. The format of the semaphore word is shown in Figure 6 - 3 . 


- 6-6 - 
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COUNTER 


WAIT 

LIST 

HEAD 


15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 


0 0 0 0 

1 1 1 1 

0 0 0 0 0 0 

l i 1_|_i l 1 | 

11 1 

_ 1 

__ 

. -.- . -J 

y 

r 

i 

k i 

1 

15 14 13 12 

11 10 9 8 7 6 5 4 

3 2 10 

_1_1_1_1_1_1_1_1_1_i 1 llli_ 


Counter (range 0-255) 
All zeroes 


Non-zero, therefore 
whole word is Wait 
List Head 


Figure 6-3. Formats of Semaphore Word 


6.5.1 R:SIG Service 

A sempahore is signalled by the R:SIG system request. This service causes the 
waiting activity that has the highest priority to be placed on the ready list. 
If no activity is waiting, the semaphore value is incremented. A semaphore 
can be signalled only 127 times without a wait. The amount of stack space 
required for this service is nine words. The format is: 


R: SIG 

sema4 


where: 

sema4 

Label of the Semaphore Descriptor Block to be 
signalled. 


6.5.2 R:WAIT Service 

An activity waits for a semaphore by using an R:WAIT system request. If the 
value of the semaphore is between 1 and 127, R:WAIT places the requesting 
activity on the ready list and decrements the semaphore. If the value is zero 
or greater than 127, the activity is inserted according to priority into the 
semaphore wait list. The amount of stack space required for this service is 
9 words. The format is: 

R:WAIT sema4 

where: sema4 Label of the Semaphore Descriptor Block to wait on. 






FILL BUFFER 


R: SIG 

XI 

SIGNAL BUFFER FULL 

R:WAIT 

X2 

WAIT FOR BUFFER EMPTY 


SDB: A 

XI,0 

BUFFER FULL SEMA4 

SOB: A 

X2,0 

BUFFER EMPTY SEMA4 
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SECTION 7 


SYSTEM CLOCKS 


7.1 INTRODUCTION 

RTX4 supports a high-resolution tick clock and a medium-resolution wall clock 
to simplify timekeeping functions for user applications. The time base for 
the two clocks is provided by the processor's Real-Time Clock (RTC). 

The tick clock provides a high-resolution clock for measuring or determining 
relatively short time intervals. It simulates the existence of multiple 
hardware RTCs. The wall clock provides a medium-resolution cIock that can 
cover all but the shortest time intervals. It provides a time-of-day and date 
facility. Figure 7-1 illustrates the interrelationships of the clocks. 
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7.2 TICK CLOCK OPERATION 

RTX4 supports a tick clock to provide measurement of very short time intervals. 
The rate of the tick clock is based on the rate of the processor's Real-Time 
Clock. 

The resolution of the tick clock is dependent on the interval of the Real-Time 
Clock. The Real-Time Clock can be internally based on the AC line frequency 
of the computer. This frequency is almost exact and has excellent accuracy 
over longer time intervals. It is sufficient for most applications. When a 
shorter interval or greater precision is required, the clock can operate from 
an external source provided by the user. An external clock rate also allows 
clocks to be synchronized with other equipment. The user of the tick clock 
© must be aware of its rate since programs may operate differently when the 
clock rate changes. 

If the required time interval is large enough and the required accuracy is 
small enough, the wall clock should be used rather than the tick clock because 
the wall clock places a significantly smaller burden on CPU resources. If the 
application requires the tick clock, however, the additional overhead is well 
worth it. 

The precision and maximum interval of the tick clock service are presented in 
Table 7-1. 


Table 7-1. Real-Time Clock and Tick Clock Parameters 





Frequency Source 



Internal 

External 

Line Frequency 

60 Hz 

50 Hz 


Clock Frequency 

120 Hz 

100 Hz 

f 

Interrupt Period 
("Tick") 

8.333 ms 

10.000 ms 

t = i 

L f 

Tick Clock Service 
Precision 

+8.333 ms 

+10 ms 

+t 

Maximum Interval 

273 seconds 

327 seconds 

t X 2 1 
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7.3 TICK CLOCK TIMERS 


RTX4 provides clock services (R:ITIC, R:MTIC, and R:CTIC) which enable 
the user to utilize the tick clock as if it were an alarm clock. 

7.3.1 R:ITIC Service 

The R:ITIC macro initiates a timer to cause a semaphore to be signalled after 
a specified number of ticks of the Real-Time Clock. This service requires 11 
words of stack space. 

The macro format is: 

R:ITIC arg 

where: arg M4D12 pointer to the argument list. 

The argument list can be generated via the TICK:A macro, which has the format: 


TICK: A 
where: 


arq,id, sema4 , count 

arg Must match the R:ITIC argument. 

id 16-bit integer used to identify this timer. 

sema4 Address of the sempahore to be signalled. 

count Number of ticks that must elapse before the 
sempahore is signalled. 


The timer identifier is a 16-bit integer. To allow for possible modification 
or cancellation of tick clock timer requests, all identifiers in concurrent 
requests within a common environment must be unique, with one exception. The 
programmer can specify any number of requests having identifiers with the 
value 0. This exception eliminates the need to create unique identifiers. 

However, a tick clock request with a 0 identifier cannot be modified or cancelled. 

In using the R: ITIC macro, the programmer must recognize the possibility that 
the first tick may occur immediately after the request is made. A one-tick 
request may, therefore, result in the semaphore being signalled in much less 
time than a one-tick interval. For this reason, requests that demark a small 
time interval should be made for one more tick than the calculated number. 


7.3.2 R:MTIC Service 

If the programmer wishes to modify a previously-initiated tick clock timer 
request, he can use the R:MTIC request However, the timer to be modified 
must have a unique (i.e., non-zero) identifier; R:MTIC cannot operate on a 
request having a 0 identifier. This service requires 15 words of stacx space. 
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The format of the request macro is: 


R:MTIC 

§13 


where: 

arg 

M4D12 pointer to the argument list. 

The argument 
format: 

1ist can 

be generated via the TICK:A macro, which has the 

TICK:A 

arg,id 

,sema4,count 

where: 

arg 

Must match the R.-MTIC argument. 


id 

Identifier of the timer to be modified; 
must be non-zero. 


sema4 

Address of the semaphore to be signalled. 


count 

Number of ticks that must elapse before the 
semaphore is signalled. 


Register A receives the return status of the R:MTIC requests. A -1 in register 
A indicates either that the specified timer identifier does not exist or that 
the timer has expired, i.e., the semaphore has been signalled. A 0 in register 
A indicates that the timer request has been successfully modified. 


7.3.3 R:CTIC Service 

The R:CTIC macro allows the programmer to cancel a tick clock timer request. 
This service requires 15 words of stack space. 

The macro format is: 

R:CTIC arg 

where: arg M4D12 pointer to the argument list. 

The argument list can be generated via the TICK:A macro, which has the format: 
TICK:A arg ,id, dmy , dmy 

where: arg Must match the R:CTIC argument. 

i_d Identifier of the timer to be cancelled: must be 

non-zero. 

dmy,dmy Dummy arguments; may have any defined value. 

The success/fail status of an R:CTIC macro is returned in register A. A -1 in 
register A indicates either that the specified timer identifier does not exist 
or that the timer has expired, i.e., the semaphore has been signalled. A G in 
register A indicates that the request has been successfully cancelled. 
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7.4 ROUND ROBIN SCHEDULING 

If several activities at a given priority level are sharing all available 
processor time, no activity at a lower priority is able to execute. However, 
any time that all activities at the higher level are inactive, round rohining 
at a lower priority level may take place. 

To support round robin scheduling, the user writes a task which alternately 
waits on the clock and invokes the R:PAUS service. One activity of this task 
must be started for each level of round robining. The activity for each level 
of the round robining must be of a higher priority than the round robin it is 
controlling. 


7.4.1 R:PAUS Service 

A call to the R:PAUS macro causes the removal of the first activity of a given 
priority from the ready list and the reentry of that activity into the ready 
list. This has the effect of dropping the seniority of the activity so that 
another activity at the same priority is allowed to execute. The service does 
'not change the priority scheduling rules of RTX4; it only changes the seniority 
rules. 

. This service requires one word of stack space. The format of the macro is: 
R:PAUS prdesc 


where: 


prdesc Priority descriptor. 
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7.4.2 R:PAUS Example 

In this example R:PAUS is used to cause two activities of the same task and 


priority to share 

processing 

time. Each 

activity gives up control every 12 

ticks. 





STACKS 

■ EQU 

7+8+7+11 

STACK SPACE FOR ROBIN 


PRIORITY 

EQU 

: 300 

PRIORITY OF ROUND ROBIN 

LEVEL 

INTERVAL 

* 

EQU 

12 

ROUND ROBIN INTERVAL IN 

TICKS 

INITIALIZATION 

* 





R:BGIN 

ABC 

FIRST LEVEL 



R:BGIN 

ABC 

SECOND LEVEL 



BGIN:A 

ABC,ROBIN,PRIORITY 


* 

R:END 





*TASK ROBIN 
* 



TDB: A 

ROBIN,START,0,0,STACKS 

START 

R:ITIC 

TIMER 


R:WAIT 

SEMA4 


R:PAUS 

PRIORITY 


JMP 

START 


TICK:A 

TIMER,0.SEMA4,INTERVAL 


SDB:A 

SEMA4.0 


Refer to Section 3.4.1. 


7.5 WALL CLOCK OPERATION 

RTX4 supports a wall clock to provide time-of-day and date for user programs. 

The wall clock uses the tick clock to keep its time. It handles both relative 

and absolute time intervals. 

The wall clock provides the following characteristics: 

•The interval of the wall clock is an absolute interval (.25 seconds) 
rather than a function of the Real-Time Clock. 

•The interval of the wall clock is sufficiently small for many human 
oriented operations. 

•The wall clock provides unique times and dates for a period of over 17 
years. 

•The processing overhead of wall clock services is much less than that of 
tick clock requests. 
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The wall clock keeps the time and date as a double-precision integer which 
counts the number of quarter seconds which have elapsed since 1 March 1976. 

The double-precision integer format allows the time and date to be kept until 

1 March 1993, which should be sufficient for most applications. 

The wall clock uses the tick clock to keep its time, so it is as accurate as 

the hardware Real-Time Clock frequency source allows it to be. RTX4 is delivered 

with a parameter which relates the wall clock period (.25 seconds) to the 
60 Hz TTLF (Twice The Line Frequency) source. This parameter must be modified 
if some other frequency source is used. 1 

The wall clock can be used to handle relative time intervals as well as absolute 
times. For instance, it may be useful to perform some functions on a daily 
basis. The programmer may add the correct number to the current wall clock 
value and request that RTX4 notify him when that absolute time is reached; or 
he may request that RTX4 notify him when a certain interval has elapsed. 
Double-precision integer values for common time intervals are: 

Interval Decimal Hexadecimal 


Quarter Second 

1 

: 1 

Second 

4 

: 4 

Minute 

240 

:F0 

Hour 

14400 

: 3840 

Day 

345600 

:54600 

28 Day Month 

9676800 

:93A800 

29 Day Month 

10022400 

:98EE00 

30 Day Month 

10368000 

:9E3400 

31 Day Month 

10713600 

:A37AOO 

Year 

126144000 

:784CE00 

Leap Year 

126489600 

:78A1400 


If the user has no need for the wall clock, he can omit it from his configura 
tion to reduce memory space and CPU usage. 


7.6 WALL CLOCK VALUE DEFINITION/ACCESS 

When an RTX4 application program begins — i.e., when it is AutoLoaded ■*- the 
wall clock has an initial value of 0. That is, the wall clock starts at time 
00:00:00 of March 1, 1976. 

The program R:ST0D and R:GT0D services allow the program to modify the wall 
clock value and to access that value, respectively. If the programmer prefers 
to deal with the wall clock value in ASCII, he can use the R:SATD and R: GATD 
services. 


1 Appendix D 




/ 
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7.6.1 R:ST0D and R:GT0D Services 


The R:ST0D macro sets the time of day to the value specified in the AQ register 
pair. (The Q register contains the least significant bits.) The value repre¬ 
sents the number of quarter seconds that have elapsed since March 1, 1976. 

The macro takes no parameters. This service requires one word of stack space. 


The R:GT0D macro allows the program to obtain the time of day at a particular 
moment during execution. The time of day (i.e., the number of quarter seconds 
that have elapsed since March 1, 1976) is returned in the AQ register pair 
with the Q register containing the least significant bits. The macro takes no 
parameters. This service requires one word of stack space. 


7,6.2 R:SATD and R:GATD Services 

The RrSATD (set time and date in ASCII) and the R:GATD (get time and date in 
ASCII) macros enable the time and date to be passed in ASCII either way between 
a task and RTX4. These services each require one word of stack space 

The R:SATD request format is: 


R:SATD arg 

where: arg M4D12 pointer to the argument list. 

The argument list is a seven-word block containing the date and time values to 
be set in the order: year, month, day, hour, minute, second, and hundredths 
of a second. (The time resolution is to a quarter second.) Any illegal 
values entered are converted to zeros. The base date is March 1, 1976; any 
earlier date is invalid. 

If R:GATD is called before the time and date are set, the values received are 
meaningless. The request format is: 

R:GATD arg 

where: arg M4D12 pointer to a seven-word block to receive the 

date and time values. 


7.7 WALL CLOCK TIMERS 

RTX4 provides three services (R:AWAL, R:IWAL, and R:CWAL) which enable the 
programmer to use the wall clock in activity control functions. 
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7.7.1 R:AWAL Service 

The R:AWAL macro initiates a timer to cause a semaphore to be signalled at an 
absolute wall clock time. Normally, the programmer specifies a time in the 
future; a time in the past causes the semaphore to be signalled immediately. 
This service requires 11 words of stack space. 

The format is: 

R:AWAL arg 

where: arg M4012 pointer to the argument list. 

The argument list can be generated via the WALL:A macro, which has the format 

WALL:A arg , id , sema4 , upper , 1ower 

where: arg Must match the R:AWAL argument. 

id 16-bit integer used to identify this timer. 

sema4 Address of the semaphore to be signalled. 

upper Upper word (most significant bits) of the 32-bit 
integer specifying the absolute wall clock time, 
represented as the number of 1/4 seconds that nave 
elapsed since March 1, 1976, at which the semaphore 
is to be signalled. 

lower Lower word (least significant bits) of the 32-bit 
integer specifying the absolute wall clock time at 
which the semaphore is to be signalled. 

The time is specified as a 32-bit integer representing the number of quarter 
seconds that have elapsed since March 1, 1976. The identifier is a-16-bit 
integer. To allow for possible subsequent cancellation of wall clock timer 
requests, all identifiers in concurrent requests within a common environment 
must be unique, with one exception. The programmer can specify any number of 
requests having identifiers with the value 0. This exception eliminates the 
need to create unique identifiers. However, a wall clock request with a 0 
identifier cannot be cancelled as can a request with a unique identifier. 


7.7.2 R:IWAL Service 

The R:IWAL macro initiates a timer to cause a semaphore to be signalled after 
a specified time interval has elapsed. This service requires 11 words of 
stack space. 
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The format is: 


R: IWAL arc[ 

where: arg M4D12 pointer to the argument list. 

The argument list can be generated via the WALL:A macro, which has the format: 


WALL:A arg , id , sema4 , upper , lower 


where: 


arg 

id 

sema4 


upper 


lower 


Must match the R:IWAL argument. 

16-bit integer used to identify this timer. 

Address of the semaphore to be signalled. 

Upper word (most significant bits) of the 32-bit 
integer specifying the number of wall clock intervals 
(1/4 second) that must elapse before the semaphore is 
signalled. 

Lower word (least significant bits) of the 32-bit 
integer specifying the number of wall clock intervals 
that must elapse before the semaphore is signalled. 


7.7.3 R:CWAL Service 

The R:CWAL macro allows the programmer to cancel a wall clock timer request 
R:CWAL cannot cancel a timer having a 0 identifier. This service requires 15 
words of stack space. The format is: 

R:CWAL arg 

where: arg M4D12 pointer to the argument list. 

The argument list can be generated via the WALL:A macro, which has the format: | 

WALL:A arg ,id, dmy , dmy , dmy 

where: arg Must match the R:CTIC argument. 

i_d Identifier of the timer to be cancelled; must be 

non-zero. 

dmy,dmy,dmy 

Dummy arguments; may have any defined values. 

The success/fail status of a R:CWAL request is returned in register A, A -1 
in register A indicates either that the specified identifier does not exist or 
that the timer has already expired, i.e., the semaphore has already been 
signalled. A 0 in register A indicates that the request has been successfully 
cancelled. 



SECTION 8 
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MAILBOX 


8.1 INTRODUCTION 

The mailbox is a facility for communicating between activities in RTX4. It 
enables 32-bit messages to be passed from one activity to another. A program 
can have any number of mailboxes. 

A mailbox is created with the MDB:A macro. RTX4 provides two mailbox services 
(R:SEND and R:RECV) for communicating 32-bit messages from one task to another 
through the Q and A registers. 

Figure 8-1 shows the general flow of processing messages. Only one message 
can be held in a mailbox at a time, but messages cannot be lost. The first 
activity to send a message deposits its message immediately and continues 
execution. A subsequent sender is suspended until the first message is 
received. The second sender then resumes execution, deposits its message, and 
continues processing. 

Each message can be received only once. If all previous messages have been 
received and an activity tries to receive a message, the activity is suspended 
until the next message is sent. Thus, no messages are received twice. 

Messages are sent and received in priority order. If several activities are 
waiting to receive a message, the highest priority activity receives the next 
message. Alternatively, if no activities are waiting, or if all activities 
are of the same priority, messages are processed on a first-come, first-served 
basis. 

The mailbox transmits an unformatted 32-bit message consisting of two computer 
words of the programmer's choice. Typically, the mailbox contains a 16-bit 
address and a 16-bit word describing what the address contains. 

Mailboxes and semaphores have some similarities. Semaphores should be used 
where only synchronization is necessary. Mailboxes can be used where data 
must be transferred between the synchronizing tasks. In such usage, a mailbox 
may replace the use of two or more semaphores and aid in simplifying the 
problem. However, a mailbox takes more space and consumes more CPU time. 



igure 8-1. Processing Messages in the Mailbox 
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8.2 MAILBOX DEFINITION 

To define a mailbox facility, the programmer calls the MDB:A macro. In addition, 
he provides two words of storage for the mailbox. The user can define any 
number of mailboxes in his program. 


8.2.1 MDB:A Macro 

The MDB:A macro defines a mailbox facility. A Mailbox Definition Block is 
provided by the user program via an MDB:A macro call. The format of the macro 
is: 


MDB:A mail 

where: mail Two character identifier to be assigned to 

the mailbox. 

8.3 MAILBOX OPERATION 

RTX4 provides the R:SEND and R:RECV services for communicating messages from 
one task to another via a mailbox. 


8.3.1 R:SEND Service 

This request causes a message to be sent from one task to another The message 
is contained in the Q and A registers. This service requires 15 words of 
stack space. 

The format of the R:SEND macro is: 

R:SEND arg 

where: arg M4D12 pointer to the argument list. 

The argument list can be generated via the MAIL:A macro, which has the format: 
MAIL:A arg , mai! 

where: arg Must match the R:SEND argument. 

mail Two character identifier of the appropriate mailbox 

as defined in the MDB:A macro. 
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8.3.2 R:RECV Service 

The R:RECV system request is used by one task to receive a message sent by 
another. The message is received into the Q and A registers. This service 
requires 15 words of stack space. 

The format is: 

R: RECV arcj 

where: arg M4D12 pointer to the argument list. 

The argument list can be generated via the MAIL:A macro as in the R:SENI) 
service above. 

8.4 SAMPLE SEQUENCE 

In the following sequence, the user defines a mailbox named 1 B1 1 and sends a 
message to that mailbox. 

MDB:A 'Bl' 

MAIL:A LABEL1, 'Bl' 


R:SEND LABEL 
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APPENDIX A 
GLOSSARY 


O 


o 


activity An execution instance of a task. Every time a task is 

begun, a new activity is created. 

activity context The activity resources that are maintained throughout the 

life of the activity. Context includes the L and K 
registers, priority, task identification, and environment 


environment The set of all the physical resources required by the 

activity, except CPU time. This includes memory, I/O 
devices, and hardware exception traps. 


environment 

memory pool The area between the end of the user's program and the end 

of memory that is used by RTX4 to allocate V-scratchpads 
and stacks for tasks as they are begun. 

interrupt latency The time that passes from when the highest priority 

interrupt is asserted by the hardware to the time it is 
v acknowledged by the CPU. It is usually caused by in¬ 

terrupt lockouts within RTX4 which are necessary for the 
internal operation of RTX4. 

list An ordered or unordered collection of blocks. 


mailbox 


A facility for communicating 32-bit messages from one 
task to another. 


priority 

descriptor A word whose high-order bit indicates whether the priority 

is absolute (bit 15=0) or relative (bit 15=1) to the 
calling task. If the word is an M4Q12 expression, the 
effective address i_s the priority. 

reentrant Used to describe a task that can have two or more activi¬ 

ties executing concurrently. 

register context The contents of registers of an activity. While the 

activity is executing, the register context is defined by 
the hardware register contents. While an activity is 
inactive, the register context is stored on the stack in 
the order P Y X Q A S L, and the pointer to the register 
context is stored in the Activity Control Block. 


« 
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round robin 


semaphore 


© 


serial 


Insuring that two or more activities share CPU time 
rather than using it on a pure priority or seniority 
basis. The user of RTX4 can implement round robin schedul¬ 
ing at a single priority level using the R:PAUS and clock 
services. 

A common data mechanism for transmitting timing signals 
between concurrently executing tasks. A semaphore has two 
operations: signal and wait. In RTX4, semaphores provide 
the primary mechanism for resource control and timing 
conflict resolution. 

Used to describe a task in which the execution of one 
activity must be completed before another activity in that 
task can start. 


system 

freepool A user-specified area that provides small buffers for RTX4 

functions such as Activity Control Blocks and Clock 
Control Blocks. 

task An ordered collection of machine instructions that perform 

a particular function within the real-time application. 


tick 


The real-time clock increment, typically 8.33 ms for 60 Hz 
line frequency. 
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APPENDIX B 
RTX4 TABLES 


B.l INTRODUCTION 

This appendix describes the following tables and the macros which generate 
them: 

• Task Descriptor Block (TDB:A) 

• Environment Control Block (ECB:A) 

• Mailbox Definition Block (MDB:A) 

• Activity Control Block 

• Clock Control Block 

• Semaphore Definition Block (SDB:A) 

• Initialization Block (INIT:A) 

• Parameter.Blocks (BGIN:A, R:SATD, R:GATD, TICK:A, WALL:A, MAIL:A) 
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B.2 TASK DESCRIPTOR BLOCK 

The Task Descriptor Block is provided by the user to describe the attributes 
of a task to RTX4. This table can be generated using the TDB:A macro. The 
address of a Task Descriptor Block is the task ID. 

TDB:A 1abel , start , yscratch , stackad , stackamt , f1ags , usage 
where: label Label to be assigned to start of TDB. 

start Starting address of task. 

yscratch Amount of Y-scratchpad used by task (for reentrant 
program only); if zero, the register value of the 
calling task is used. 

stackad Address of preallocated stack (for serial program 
only); if zero, stack space is allocated by RTX4. 

flags None currently defined. 

usage Number of concurrent activities of this task (optional). 


0 

1 

2 

3 

4 

5 

6 

7 

8 
9 

IQ 

11 


TD:PER 

TD:FLG 

TD:USA 

TD:NOX 

TD: Y 

TD: AD 

TD:AMT 

TD: P 

TD:CSA 



TD:CKW 


0 

1 

2 

3 

4 

5 

6 

7 

8 
9 
A 
B 
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Field 

Word 

Bits 

Description 

3 1 

TD:PER 

0 

0-15 

Link pointer to the list of other Task Descriptor 
Blocks, the head of which is in ECBTLH (word 16) 
of the Environment Control Block. This list is 
linked as part of the loading process. 


TD:FLG 

1 

0-15 

TDB flags; none currently defined. 


TD:USA 

2 

0-15 

Either: controls the number of concurrent 
executions of a reentrant task, or queues 
requests for execution of a serially reusable 
task. 

O 

TD:NOX 

3 

0-15 

Maximum permitted number of concurrent executions 

of a reentrant task. 


TD: Y 

4 

0- 15 

Length of the Y-scratchpad to be dynamically 
allocated to each execution of this task. If 
the length is zero, the Y value of the task tnat 
called this task for execution is retained. 


TD: AD 

5 

0-15 

Either: the address of the area to be useu as 
the stack for each execution of this task or 0, 
if the stack is to be dynamically allocated 

j 1 

| TD:AMT 

6 

0-15 

Either end limit address of the stack if TD :AD 
i- 0; or if TD:AD = 0, it is then the stack length 


TD: P 

7 

0-15 

Address of the start of task execution. 


TD:CSA 

8 

0-15 

Concurrency semaphore. 



9-10 


Reserved. 


TD:CKW 


n 


0-15 


TDB checkword; contains :FOIE. 


m 
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B.3 ENVIRONMENT CONTROL BLOCK 


Ixv/i^ nV1 ronmen ^ ^ on ^ ro ^ Block is created by the user to describe resources to 
The address of the ECB is its ID. This block can be generated using 
the ECB:A macro. a 

ECB:A label t uat 

where: ^ abe i Label to be assigned to start of ECB; 

referenced in INIT:A. 


uat Address of the 


© ° 

EC:PER 

0 

1 

EC:FLG 

: 1 

2 

EC:EDB 

: 2 

3 

EC:LUS 

: 3 

4 


■ O 

5 


: 5 J 

6 

EC:CNT 

: 6 

7 

EC:ALH 

: 7 

8 

EC:SUB 

:8 

9 

EC:MST 

: 9 

10 

EC:NEC 

: A 

11 

EC: CKW ; 

:B 

12 

ED:EV0 

: C 

O 13 

ED:MR0 

: D 

14 


:E \ 

15 


: F / 




16 

ED:EVT 

: 10 



► 

31 

ED:EVT 



(table continues on next page) 


Unit Assignment Table. 1 

Peer link. 

ECB flags - none defined. 

Environmental descriptor block pointer. 
Logical unit semaphore. 

Reserved 

Number of task activities. 

ACB list head. 

Subordinate list head. 

Master environment. 

Necessary environment. 

ECB checkword; contains :F06E. 

Exception vector offset (=16). 

Map register offset (=48). 

Reserved 


Exception Vector Table 


^nput/Output Subsystem I0S4 User's Manual (90-93430-00) 
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(continued from previous page) 


32 

ED:UAT 

33 

ED: LMA 

34 

ED:MPA 

35 

ED:HMA 

36 

ED:EUS 

37 

ED:PRI 

38 

ED:TLH 

39 

ED: SLH 

40 

ED:MLH 

41 


42 


43 


44 

Undefined 

45 

Undefined 

46 

Undefined 

47 

Undefined 

48 

Undefined 


20 

21 

22 

23 

24 

25 

26 

27 

28 



2C 

2D 

2E 

2F 

30 


Unit Assignment Table address 
Low memory address 
Environment pool address 
High memory address 
Environmental usage semaphore 
Maximum priority 
Task list head 
Semaphore list head 
Mailbox list head 

Reserved 

Number of task activity 
TDB of initial task 
Priority of initial activity 
ID of initial activity 
Map register table 





-m 


ComputarAutomation ■ 


B.4 MAILBOX DEFINITION BLOCK 

A Mailbox Definition Block is provided by the user to provide a mechanism 
for communication between activities. An MDB can be generated via the MDB:A 
macro: 


MDB:A mail 


where: 


mail 


Identifier to be assigned to the mailbox. 



Two words of staorage must be provided for the mailbox. 


0 

MD:PER 

:0 

1 

MD:FLG 

: 1 

2 

MD:MBX 

:2 

3 

MD:MSG 

:3 

4 

MD: A 

:4 

5 

MD:Q 

:5 

6 


:6 

7 


:7 

8 


:8 

9 

MD:ECB 

:9 

10 

MD: ID 

:A 

11 

MD:CKW 

:B 


Peer link 
MDB flags 

Mailbox usage semaphore (initially = 1) 
Message signalling semaphore (initially 
A register of message 
Q register of message 

Reserved 

Master environment 
ID 

MDB checkword; contains :F07E 


0 ) 


•* B-6 
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B.5 ACTIVITY CONTROL BLOCK 

RTX4 creates the Activity Control Block when an activity is begun. 


0 

AC:PER 

1 

AC:FLG 

2 

AC:PRI 

3 

AC: K 

4 

AC: Y 

5 

AC: L 

6 


7 

AC:LST 

8 

AC:TDB 

9 

AC:ECB 

10 

AC: ID 

11 

AC:CKW 


:0 Peer link 

:1 ACB flags 

:2 Priority 

:3 K register 

:4 Y register initial value 

:5 L register initial value 

:6 Reserved 

:7 Environment activity peer link 

:8 Master TDB 

:9 Master ECB 

:A ACB identifier 

:B ACB checkword; contains : F02F 
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B.6 CLOCK CONTROL BLOCK 


The Clock Control Block is created by RTX4. 


0 

CC:PER 

1 

CC:FLG 

2 

CC:TIC 

3 


4 

CC:STS 

5 


6 


7 


8 


9 

CC:ECB 

10 

CC: ID 

n 

CC:CKW 



Peer link 
CCB flags 

Tick clock expiration 

Not applicable to tick clock 

Semaphore or address of semaphore 

Reserved 


Master environment 
CCB identifier 

CCB checkword; contains :F04E 
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B.7 SEMAPHORE DEFINITION BLOCK 

The semaphore definition block is provided by the user to control the synchro- 
nization of tasks. This table can be generated using the SDB:A macro. 

SDB:A label , value 

where: label Address label of the semaphore. 

value Initial value of the semaphore. 



0 Peer link 

1 SDB Hags; none defined (bits 8-1 b) 
Semaphore initial value (bits 0-7) 

2 Semaphore word for waiting task 


3 


3 SDB checkword; contains :F03E, 
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B.8 INITIALIZATION BLOCK 


The Initialization Block is generated by the INIT:A macro and provides the 
information needed to initialize the entry point. In order to use this macro, 
the user must declare the label R:INIT as an external in his program (NAM RINIT), 
This macro must preceed any other code in the program. 


INIT: A a,q,x,.y, ecb , tdb , pri 

INIT:A a,q,x,y,ecb,tdb, pri , amtfree 

INIT:A a,q,x,y, ecb , tdb , pri , amtfree , adrfree 

INIT:A a,q,x,y, ecb , tdb , pri . amtfree , adrfree , topmem 

INIT:A a,q,x,y, ecb , tdb ,pri,,. topmem 

INIT:A a,q,x,.y , ecb , tdb , pri , amtf ree ,, topmem 


© 


where: 


a, 3 ,x,y Initial values of the A, Q, X, and Y registers 

ecb Address of the Environment Control Block 


tdb 

Pri 

amtfree 

adrfree 

topmem 


Address of the Task Descriptor Block 
Activity priority 

Amount of freepool space (optional) 

Address of the freepool (optional) 

Upper limit of memory available to RTX4 
(optional) 


When an optional parameter is omitted, a comma must be inserted to hold 
the position of later parameters. 

© 

0 
1 
2 

3 

4 

5 

6 

7 

8 

9 

10 


IN: A 


IN: Q 


IN: X 


IN: Y 


IN:ECB 


IN:TDB 


IN:PRI 


IN: ID 


IN:FPL 


IN:FPA 


IN:EOM 


0 Initial contents of A register 

1 Initial contents of Q register 

2 Initial contents of X register 

3 Initial contents of Y register 

4 Address of Environment Control Block 

5 Address of Task Descriptor Slock 

6 Initial activity priority 

7 Block identifier 

8 Freepool length (words) 

9 Freepool address 

A End-of-Memory address 


- 8-TO - 
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APPENDIX C 
RTX4 EXCEPTIONS 


When an error i«? dicroveroil dm imj 11 in nvnritl inn of RT\I. .in n\i opt inn i omli 
(ion la generated. Kerer Lo LULA Mai.ro to aoe how to link in a user exception 
processor. The names of the form XV:xxxxx, listed in the table below are used 
to define exception vectors for processing exceptions. 

Table C-l. RTX4 Exceptions 


EXCEPTION 

If*exception processor 

If no exeption, processor 

TYPE 

specified JMP to routine 

CPU HALTS, with following 


specified in E0B. 

register contents. j 

.— 


, <j " ■ no' e“> '; < 

instruction 

trap 


X = Note 2. 

Q = 0 = XV:UINTP 


X = Note 6. 

Q = 0000 
P = 80 


Memory 

exception 

trap 


A = Note 3. 

X = Note 4. 

Q = 1 = XV:MEMTP 


Character/ 

mnemonic 

exception 

trap 


A = Note 1. 

X = Note 2. 

Q = 2 = XV:CNMTP 


User 

trap 


A = Note 1. 

X = Note 2. 

Q = 3 = XV:USRTP 


Arithmetic 

exception 

trap 


A = Note 1. 

X = Note 2. 

Q = 4 = XV:AERTP 


Stack 

exception 

i t ..‘i 


A • Ur t U>- I 
‘I 


A = 208 
X = Undefined 
Q = 0001 
P = 80 

A = 208 
X = Note 6. 

Q = 0002 
P = 80 

A = 208 
X = Note 6. 

Q = 0003 
P = 80 

A = 208 
X = Note 6. 

Q = 0004 
P = 80 

A 

f If, I -■ - 

M i|n‘u 


>V .;•££’(■ $|^§| 
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Table C-l. RTX4 Exceptions (Continued) 


EXCEPTION 

TYPE 

If exception processor 
specified JMP to routine 
specified in EDB. 

If no exeption, processor 

CPU HALTS, with following 
register contents. 

Unimplemented 

A = Undefined 

A = 208 

system 

X = Contents of Strap trap 

X = Address where exception 

service 

location (next P) 

occurred 


Q = 8 = XV:USTEX 

Q = 0008 



P = 80 

Strap 0 

A = Undefined 

A = Undefined 


X = Undefined 

X = Undefined 


Q = 9 = XV:STOEX 

Q = 000A 

V 


P = 80 

RTX door 

A = Negative error code 

A = Error code on door exit 

service 

X = Undefined 

(positive value), see 

exception 

Q = :A = XV:DOREX 

Table C-2 



X = Undefined 



Q = 000A 


! 

P = 80 

RTX 

i •». 

A = Negative error code 

A = Error code (positive 

system 

X = Location where error 

value) 

error 

occurred +1 . 

X = Location where excep¬ 


Q = :B = XV:RTXEX 

tion occurred +1, see 



Table C-2 



Q = 000B 



P = 80 


NOTES: 


1. Contents of trap location +1 (instructions causing trap). 

2. Contents of trap location (next P). 

3. Contents of trap location +1 (undefined). 

4. Contents of trap location (undefined). 

5. Contents of trap location +1. 

6. Address where exception occurred +1. 
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Table C-2. Error Code Indicators 



DEFINITION 


SEMAPHORE EXCEPTION 
STRAP OUT OF RANGE 
INSUFFICIENT STACK SPECIFICATION 
UNABLE TO FILL E.M.P. REQUEST 
UNABLE TO FILL SYSTEM FREEPOOL 
NEGATIVE ACTIVITY PRIORITY 
CCB EXCEPTION, TICK CLOCK 
HARDWARE TRAP EXCEPTION 

(X register contains address of hardware *^ap) 
DEBUG VERSION, TABLE ID CHECK FAILURE 
DEBUG VERSION, SYSTEM ACTIVITY VIOLATION 
CCB EXCEPTION, WALL CLOCK 
MAILBOX ID CHECK (INVALID ID) 
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APPENDIX D 

CONFIGURATION OPTIONS 


D.l INTRODUCTION 

Configuration options allow the user to tailor his system to meet his needs. 

D.2 NONSTANDARD LINE FREQUENCIES 

The RTX4 wall clock provides accurate time to +.25 second precision. RTX4 is 
delivered with a parameter which relates the wall clock period to the 60 Hz 
TTLF (Twice the Line Frequency) source. If some other frequency source is 
used, the programmer must set the contents of location TTLF4: to half the 
value of the Line Frequency of the Real-Time Clock used. (The absolute location 
of TTLF4: can be found in the load map.) The default TTLF4: value, for 60 Hz, 
is 30 (:IE). 

The RTX4 source module CLK50: is provided for setting TTLF4: to the correct 
value for a European system with a Real-Time Clock using 50 Hz Line Frequency, 

A user on this type of system needs only include the statement: 

LOAD CLK50: 

in his program to set TTLF4: to the appropriate value, 25 (:19). 


D.3 PROGRAM RESTARTS WITHOUT RELOADING 

Normally, the programmer must load a fresh copy of his program in order to 
restart. Many variables and pointers are initialized during loading, reducing 
the size of RTX4 initialization code. Reloading is simple when disk storage 
is used. However, in paper tape development and some other circumstances, the 
programmer must be able to restart an RTX4 program without reloading. 

In these cases, the programmer can invoke the REINI: option via a LOAD directive 
in any user module: 

LOAD REINI: 

By invoking the REINI: option, the user assures that all RTX4 variables and 
pointers are reinitialized whenever RTX4 is restarted. 
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D.4 DEBUGGING FACILITIES 

The Debugging Monitor allows debugging of RTX4 applications. One of the options 
described below can be included to start execution in DEBUG rather than in 
RTX4. The programmer can then start RTX4 by jumping or breakpointing to loca¬ 
tion :80, the normal start location. If an unresolved error condition occurs, 
a pseudo-breakpoint occurs at location :7E rather than a halt at :7F. 

See the NAKED MINI 4 Debugging Monitor Reference Manual for complete informa¬ 
tion on the Debugging Monitor. 


D.4.1 The DEBUG4 Option 

This option includes the standard version of the Debugging Monitor. This 
version provides the following commands: 

A Assign list output device. 

J Re-enter user program or set temporary breakpoints. 

B Set temporary breakpoints or re-enter user program. 

R Display or change user program registers. 

G Display or change general register. 

I Inspect memory. 

L List memory. 

F Fill memory. 

S Search memory. 

Z Print chain. 

D Dump memory. . 

V Verify memory. 

W Load binary tape. 

This option is invoked via the following LOAD directive in any module: 
LOAD DEBUG4 


D.4.2 The MDBUG4 Option 

This option causes the MDBUG4 version of the Debugging Monitor to be included. 
MDBUG4 provides all of the DEBUG4 commands except: 

Z Print chain. 

W Load binary tape. 

D Dump memory. 

V Verify memory. 

A Assign list output device. 


This option invoked via the following LOAD directive in any module: 


LOAD 


MDBUG4 
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D.4.3 The XDBUG4 Option 

This option causes the XDBUG4 version of the Debugging Monitor to be included 
XDBUG4 provides all of the DEBUG4 commands plus: 

M Monitor computer bus. 

T Intercept traps. 

This option is invoked via the following LOAD directive in any module: 

LOAD XDBUG4 


D.5 WALL CLOCK OMISSION 

The NOWAL: option allows the programmer to omit the wall clock from his config- 
ration. If the programmer has no need for the wall clock services, he can savr 
the time and space normally used for these services by invoking this option via 
a LOAD directive in any user module: 


LOAD 


NOWAL: 
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APPENDIX E 

RTX4/I0S4 APPLICATION DEVELOPMENT SYSTEM GENERATION USING 0S4 


E.1 INTRODUCTION 

This appendix outlines a suggested procedure for creating a system for developing 
RTX4/I0S4 application programs using the 0S4 system. This discussion provides 
specific, step-by-step instructions for generating such a system on a floppy 
diskette. The user can modify this procedure as necessary to suit his particular 
needs. 

A sample RTX4/I0S4 application appears at the end of the appendix. 


E.2 RECOMMENDED PROCEDURE 

To generate an RTX4/I0S4 application development system on a floppy diskette, 
the programmer can take the following steps: 

1. AutoLoad the 0S4 system diskette. (The AutoLoad procedure is described 
in the 0S4 System User's Manual and the NAKED MINI 4 AutoLoad manua! 

2. Install a new, formatted diskette in Unit 1. 

3. Label the new diskette as described in the 0S4 user's manual or in 
the I0S4 user's manual. 

4. Remove the 0S4 system diskette from Unit 0; install the RTX4 product 
diskette (F4100 

5. Enter the command: 

/COPY DF1=DF.RTX.LIB 1 

6. Remove the RTX4 product diskette; install the RTX4 macros diskette 
(F42501). 

7. Enter the command: 

/COPY DF1=DF.GEN.MAC 
/COPY DF1=DF.RTX.MAC 
/COPY DF1=DF.IOS.MAC 
/COPY DF1=DF.SFM.MAC 1 


x If any problem arises during this step, the user must re- install and AutoLoad 
the 0S4 system diskette and then retry this step. 
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8. Remove the RTX4 macros diskette; install the I0S4 product diskette 
(F43001). 

9. Enter the command: 

/COPY DF1=DF.IOS.LIB 

10. Remove the I0S4 product diskette; install the SFM product diskette 
(F44001). 

11. Enter the command: 

/COPY DF1=DF.SFM.LIB 1 

12. Remove the SFM product diskette; install the 0S4 system diskette. 

13. Enter the command: 

/COPY DF1.PROGRAM.ASM=CI 

and respond to the > prompt by entering the symbolic text of the 
application program; enter a /* command to signal the end of the 
text. 

14. Build a JCL file by entering the command: 

/COPY DF1.PROGRAM.JCL=CI 

and respond to the > prompt with the lines: 

/MACRO PROGRAM(DEFINITION=GEN+RTX+IO$+SFM) 

/LINK PR0GRAM(AB=100)+SFM+I0$+RTX 

Enter a /* command to signal the end of the text. 

15. Enter the command: 

/DO PROGRAM 

to execute the JCL file, which assembles and links the program. 

16. Enter the command: 

/AUTOLOAD DF1.PROGRAM.BIN 
to execute the program. 

17. Debug the program (assuming DEBUG4 was loaded with the program). 


x If any problem arises during this step, the user must re-install and AutoLoad 
the 0S4 system diskette and then retry this step. 
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18. If corrections to the symbolic version of the program are required, 
take the following steps: 

a. AutoLoad the system diskette. 

b. Edit the file PROGRAM.ASM by entering the command: 

/EDIT PROGRAM 

c. Perform steps 15, 16, and 17. 

d. If necessary, perform step 18. 

19. If the completed application is to reside on the development diskette, 
rename PROGRAM.BIN or copy it to another file. (To preserve the 
source code of the program, copy PROGRAM.ASM to another file. To 
preserve the object version, either rename PROGRAM.OBJ or copy it to 
another file.) Alternatively, copy PROGRAM.BIN (and optionally 
PROGRAM.ASM and PROGRAM.OBJ) to another medium (eg., paper tape or 
another disk). 

This procedure produces a binary file which can be loaded into any NAKED 
MINI 4® Family computer. If the file resides on a disk, it can be loaded via 
the /AUTOLOAD command. If the file has been copied to paper tape, it can be 
loaded via the hardware AutoLoad procedure. The system diskettes are left 
intact and can be stored in a safe place for backup. The following files are 
created on the development diskette: 

RTX.LIB 
GEN.MAC 
RTX.MAC 
IOS.MAC 
SFM.MAC 
IOS.LIB 
SFM.LIB , 

PROGRAM.ASM 
PROGRAM.JCL 

PROGRAM.OBJ (unless renamed in step 19) 

PROGRAM.BAK (created when PROGRAM.ASM is edited in step 18) 

PROGRAM.BIN (unless renamed in step 18) 

and any files created by copying PROGRAM.ASM, PROGRAM.OBJ, and/or PROGRAM.BIN 
in step 19. 

To develop another application, the user needs only edit the PROGRAM. ASM file 
to contain the new source text and then perform steps 15-19 outlined above. 


NOTE 


This procedure assumes the standard 0S4 configuration, 
UF logical unit is assigned to the DF01 physical unit, 
other assignment in the user's configuration, the user 
device specification in the file identifiers specified 


in which the 
If UF has some 
must include the 
in steps 14 and 15. 


E.3 SAMPLE APPLICATION PROGRAM 


The following pages present the assembly listing, link map, and diskette view 
of a sample RTX4/I0S4 application program. 





Figure E-l. RTX4/I0S4 Example Application Program, Page 1 of 7 



# 




© 


PAGE 0001 MACRO (Cl) RTX<4/IOS4 EXAMPLE APPLICATION PROGRAM 
1979/01 /18 20541521.25 1NI11ALIZAT ION 



0000 

0 00 3 


N A M 

R 5 IN I f 

INI 1 I At IZATION BLOCK MAf t 



00 04 


£ X T R , 

ECB 

ENVIRONMENT CONTROL H L o L A 



0 0 0 5 


EX TR 

IDB 

TASK DESCRIPTOR BLOCK 


00000000 

0006 

AR 

EDO 

0 

INITIAL A REGISTER, 


00000000 

0 0 0) 

OR 

EDO 

.0 

0 REGISTER# 


00000000 

0008 

XH 

EUU 

0 

X RtGISIER# 


00000000 

0009 

YR 

EQU 

0 

AND Y REGISTER 


0 0 0 0.0 0 0 A 

0 0 1 0 

PRIOR 11 Y 

EUU 

10 

ACTIVITY PRIORITY 


00000100 

0011 

FRfcEPOOL 

E NO 

5 100 

EREEPOOL SIZE 

UOOU 

00 0 0 

0012 


1NI 1 5 A 

A R , 0 R , X K , 

YR#ECb# TDD,PRIOR IT Y,EREEPOOL 

0001 

0000 






0002 

0000 






0003 

0000 






0004 

000 5 






0005 

0002 






0 0 06 

0 00 A 






0007 

FOOE 

0012 + 





0 00 8 

0 100 

0012 + 





0009 

0 0 OB 

0012 + 





000 A 

0000 

0012 + 





0 0 OH 

8080 

0012 + 







0013 


END 



0 00 0 

ERRORS 

(0000) 





0000 

WARNINGS 

(0000) 
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PAliE 0 00 3 MACHO (Cl) RIX4/10S4 EXAMPLE A PPL 1 C A 1 1 UN PROGRAM 
1979/01/18 20:41:28.00 THE TASK 




0023 

* (ASK 

DESCKIPTOH 

BLOCK 



00 00 

0024 


NAM 

TUB 

TUB NAME 


0 0 0 0 0 00 0 

0025 

ST ACE AD 

F Q11 

0 

HAVE R1X ALLUCATE S 1 ACK 


00000050 

0 0 28 

ST ACK AM 

EUO 

: 50 

S1ACK SIZE 


00000000 

0 0 2 7 

Pi ADS 

EUU 

0 

NO FLAGS 


00000001 

0o28 

USAGE 

KUO , 

l 

ONE CONCURRENT ACTIVITY 

0 000 


0029 


1 D u : A 

fOh,START, 

0, STA C KA i),S 1ACKAM,FLAGS,USA bE 

0001 

0 0 40 

0 0 29 + 





0002 

0 0 08 

0 0 29 + 





0003 

0001 

0029 + 





0004 

0000 

0029 + 





0005 

000 0 

0029 + 





UOOfe 

0050 

0 0 29 + 





0007 

OOOC 

0 0 2 9 + 





0 008 

0001 

0029 + 





0009 

0 0 0 0 

0 0 2 9 + 





0 0 OB 

KUIE 

00 29 + 







00 30 

* THE ACTIVITY 




oooooooc 

0031 

S T A R 1 

EUU 

$ 

START ADDRESS 

OOOC 

3 A 07 

0 0 32 


J : iu 

CRT IUH 

OPEN THE CRT 

0000 

0 017 

0032 + 





OOOE 

OEOO 

0 0 5 3 


HLT 


ABNORMAL RETURN 


00000OOP 

0 0 34 

LOOP 

EUU 

S> 


OOOF 

5A07 

00 35 


I: JO 

MSG IOB 

WRITE' MESSAGE TO CR1 

0010 

00 IF 

0035 + 





0011 

OEOO 

0 0 38 


HL1 


ABNORMAL RE TORN 

0012 

3A0B 

0037 


H : I T 1 c 

T ] MEK 

START TJMER 

0013 

002F 

0 0 3 7 + 





0014 

3A02 

0 0 36 


R : Vi A I T 

Sc M A 4 

wAll FOR TIMF. TO EXPIRE 

0015 

0035 

0 0 36 + 





00 16 

9fc 78 OOOF 

0 0 39 


JMP 

L UuP 

GO DISPLAY MESSAGE AGAIN 



0 0 4 0 

* I/O BLUE8 TO OPEN CH f 


0017 

5458 

0 0 4 1 


Hid ; a 

CRT I Oh, 'TV 

• ,Fu:, op:, o,o,o 

0018 

0 000 

0041 + 





0 019 

0000 

0 0 41 + 





0 0 1 A 

o 

o 

0 0 41 + 
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PAGf 0004 MACRO (Cl) kTX 4/J0S4 EXAMPLE APPLICATION PROGRAM 
19/9/01/th 30 5 41 536.50 1 Mb TASK 


0 0 1 B 

0 0 0 0 

0 0 4 1 + 





00 1C 

0 0 0 0 

0 V 4 1 + 





0011) 

0 0 0 0 

0 0 4 1 + 





0 0 1 E 

0 0 0 0 

0 0 4 1 + 







0 0 43 

* I/O BLOCK ,10 

/.KIT [ 10 CRT 


0 0 1 F 

*5456 

004 3 


1 US 5 A 

MSG i OB , 1 T V ’ , rtR 

:, Fa:,count,buff er, o 

0030 

0 0 0 0 

0 04 5 + 





0031 

0000 

0 0 4 5 + 





0033 

0018 

0 0 4 3 + 





0 03 5 

0010 

0043 + 





0039 

0037 

0 0 4 5 + 





0035 

0 0 0 0 

0 0 4 3 + 





003b 

00 00 

0 0 4 3 + 







0 0 44 

* MESSAGE 

T t x 1 

B U F F l: R 



00000000 

0045 

CR 

EDO 

: wD 

ASCII CARRIAGE RE T OKU 


00 0 0 000 A 

0 0 4b 

LF 

EDO 

: o'A 

ASCII LINE FEED 

0037 

30 40 

0 U 4 7 

BUFF ER 

BY It 

1 MESSAGE 11 X1 

' ,ck,lf 

0038 

4553 






0039 

534 1 






0 0 3 A 

4745 






0 0 3B 

3 0 5 4 






003C 

4558 






0 0 30 

5430 






003E 

00 0 A 







00000010 

0 0 4 8 

COUNT 

too 

S-BOFF Kk*3 

BYTE COUNI 



0 0 4 9 

* f i ME K C 

UNT ROL 

BLOCK 



0 0 0 0 0 0 3 F 

0 0 50 

10 

t UI.J 

S 

Ur,- 1 Jilt, lb Hi! flMK ] 


00000358 

0 0 51 

TICKS 

too 

130*5 

TIME = 5 SECONDS 

0 0 3F 

0 0 0 0 

0053 


1 1 C K : A 

TIMER, I 0 , St. m A 4 

,11CKS 

0 0 3 u 

0 0 3 F 

0 0 53 + 





00 31 

0 0 55 

0-4 53 + 





0033 

0358 

0 0 53 + 







0 0 5 5 

* SEMAPHORE DESCRIPTOR BLOCK 



00000000 

*<>0 54 

V • * L 1 i h 

t Oil 

i. 

INITIAL VALUE 

0 0 3 3 


0 0 5 5 


S 0 H * A 

SF MA4 , V AL Ut 


0 0 39 

0 0 0 0 

0 0 55 + 
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PAGE 000b MACRO CC1) KTXO/IOSO EXAMPLE APPLICATION PROGRAM 
1979/01/18 20:41:30.00 THE TASK 

0035 0000 0U55 + 

003fa F03E 0055 + 

OuSb LNO 

0000 ERRORS (0000) 

0000 WARNINGS (0000) 
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PAGE 

0006 MACRO (Cl) 

K1X4/I0S4 EXAMPLE APPLICATION 

1979/01/lrt 20: 

41 • 3 4 ,.0 0 

ti\IV IRUNMEfi r CONTKUL BLOCK 


0000 

0059 

N A M E C B 



0060 

E X I R U A T 

0000 


0061 

ECB:A ECri,IJAT 

OOOi 

0000 

0 0 61 + 


0002 

0 00 0 
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APPENDIX F 


RTX4 DEMONSTRATION PROGRAM 


The RTX4 Demonstration Program is designed to exercise the system services of 
RTX4. The services exercised are: 


R:BGIN 


• R:SIG 


• R:WAIT 


R:CINT 


Begin on activity 
Signal a semaphore 
Wait on a semaphore 
Wait for console interrupt 


R:ITIC 


Tick clock timer 


When the program is executed it transfers immediately to DEBUG4. To begin 
execution of the program, jump to location :80. From here the program goes 
through the initialization, then begin an activity of the Master Task. This 
activity waits for a console interrupt. At this time the system is in the 
dispatcher idle loop^ which is indicated by blinking the byte mode and overflow 
indicator lights. The user should now press console interrupt which causes an 
activity of the Timer Task to be started by the Master Task. Each of the next 
15 console interrupts causes another timer activity to start until 16 timer 
activities exist. All subsequent console interrupts are ignored. 

Each timer activity causes a different bit of the console data register to 
blink. The location and frequency of these bits is determined by a table. 

The frequency is based on tick clock intervals. 

At any time a power fail may be caused and the system recovers completely when 
power is restored, provided the memories are properly powered. 



The missing external R:DBUG which shows on the link map will not 
affect the execution of RTX4. 




Figure F-1. RTX4 Demonstration Program, Page 1 of 13 


PAGt 0001 MACRO (It) 
19 7 9 / 01/17 02 : 59 : 34,25 


* 


0000 


0000000ft 


0000 0000 
0001 0000 
0002 0000 
0005 024A 
0004 03oA 
0005 02OB 
0006 0100 
0007 FOOE 


0 0 0 2 
0 0 0 5 
00 0 4 
0 0 05 
0 0 0 ft 
0007 
0 0 0 ft 
0009 
0 010 
001 1 
0012 
00 13 
00 14 
00 15 
0016 
(>0 17 
001 8 
0019 
0 0 20 
0021 
0022 
0023 
0024 
0025 
0026 
0027 
0 0 2ft 
0029 
0 0 .5 0 



© 


U 1X4 1)1 Mil HK'UGKAh NO, 


9 54 10-1 0 B 3 


* 

* 

* 

★ 

* 

* 

it 

it 

it 

it 

it 

it 

it 

it 

it 

it 

* 

THLvSIZ 

it 

it 

it 

it 

it 

it 

it 


NAM R:INIT 

LOAD RE IN1 • 

LOAD debugs 

THIS HR ObR A M TESTS ThE TICK CLOCK SERVICES. 

THE f t ST CONSISTS OF TftU I ASKS, THE MASTER 
AND THE TIMER. THE MASTER IS THE INITIAL 
TASK AND THERE IS ONLY ONt ACTIVITY OE 
IT. THIS ACTIVITY BEGINS AN ACTIVITY OF 
THE UMEk TASK EACH TIME CONSOLE INTERRUPT 
IS PRESSED, UNTIL 16 ACTIVITIES OF THE TIMER 
TASK ARE BEGUN. FURTHER CONSOLE INTERRUPTS 
ARE IGNORED. 

THE TIMER TASK MAKES A TICK CLUCK REQUEST 
ACCORDING TO THE PARAMETERS IN IIS Y SCKAICHPAO. 
ftHEN THE TIMER EXPIRES IT COMPLEMENTS A 
BIT IN THE CONSOLE ftORU REGISTER AND KEPEA1S. 

EUU 8 NUMBER OF ftURD/TABLE ENTRY 

BEGIN MASTER TASK ftllH: A=0 

Q = 0 

x = o 

Y = T ABLE 

AT PRIORITY riuo ft!IH :?00 WORDS OF FREEPODL 


INI! ;A U, 0, 0, TABLE, ECB1 , MS TRTD, : 1 0l) f JifOp 


0 0 30 + 





Figure F-1. RTX4 Demonstration Program, Page 2 of 13 




Figure F-i. RTX4 Demonstration Program, Page 3 of 13 



i. 


-r:- ; • - =< 


O O 

PAGE 0005 MACRO (Cl) RTX4 Uf lU PkOGRAM Nil. } 93910~10 m3 

1979/01/17 02:59:35. 7b MASTER fASK 




0 0 32 

* 





00 3 3 

* 

THIS Task BEGINS THE TIMER I ASK. 



0 0 34 

* 

EACH TIME CONSOLE InTEKROPI IS PRESSED 



0 0 35 

* 

A N E M 

TIMER ACTIVITY IS CREATED. 



00 56 

* 





0 0 37 

* 


S' 



0 0 38 

* 

MASTER TASK NILL HAVE Y ENUAL To 1 ABLE 



00 39 

* 


1 35 NURDS OF SlACK, SYSTEM ALLOCAlEl 



0040 

★ 


1 POSSIBLE CUNCURRENl EXECUTIONS 



0 0 4 1 

* 



020B 


0042 


T l>B ; A 

MSIRTO,MASTtk,0,0,:35,0,1 

020C 

0040 

0042 + 




0201) 

021 3 

0042 + 




020E 

qooi 

0 0 4 2 + 




0 2 OF 

0000 

0042 + 




0210 

00 0 0 

0042 + 




0211 

0035 

0042 + 




0212 

0217 

0 042 + 




0213 

00 01 

0042 + 




0214 

0000 

0042 + 




0216 

FOIE 

0 0 4 2 + 





00000217 

0043 

MASTER 

EDO 

$ 

0217 

4910 

0 0 44 


COPY 

=16,0 ALLOW ONLY 16 TIMERS 


00000218 

0 0 45 

LOOP 

ERU 

S 

0218 

5546 021F 

0046 


JE RD 

R,NOMOKE IF 16 TIMERS ALREADY 

0219 

1 A08 

0047 


R : CI NT 


02 i A 

0 0 0 0 

0 0 4 7 + 




021 H 

1 A03 

00 48 


R :BG IN 

TDHCY) BEGIN TIMER ACTIVITY 

02 1C 

1000 0000 

0 0 4 8 + 




021!) 

6608 

0 049 


ADD 

=TOLSIZ,Y MOVE TABLE POINTER TO NEXT ENTRY 

0 2 IE 

9E 7 9 0218 

0 0 50 


JMP 

LOOP wFPFAT 



0 0 51 

* \h 1IME P5 ARE 

RUNNING, IGNORE F O hiHER CONSOLE' INTENOP 1 S 


0 0 0 0 0 2 1F 

0052 

MUM!) WE 

FRO 

S 

02 1 F 

l Aoa 

0 053 


R : C I N T 


0220 

0 0 0 0 

0 0 53 + 




0 221 

91 71) 02 l F 

0054 


•JMP 

NOMURE 






Computer Auto; 





ComputerAutonurtion - 


"C 

O 


© 




x 


© 

X 


■3 



X 

'!ir 

< 


2 

»— 


Jj 



© 

X 



‘XI 


cr 

»— 


X 



<— 



*»» 




IT 



»n- 


Li 

• 

IP 

— > 

r— 

in 


y> 

o 

O 

•• 

© 

X 

T 


w 



<t 

• • 


X 

XI 



o 



IN* 


© 

—* 

w* 

© 

\ 

© 

© 

r-« 

© 


© 

/—s 




UJ 

cr 

XI 

LH 

r— 

cu 

C 

cr 

OJ 

X 

*■« 

© 


Figure F-l. P"X4 Demonstration Program, Page 4 of 1 3 





Figure F-l. RTX4 Demonstration Program, Page 5 of 1 


o-’ 


o 


o 


PAGE 0005 MACRO (Cl) RTX4 DEMO PROGRAM NO. 1 9 5410-10 05 

1979/01 /1 7 02S59S37.75 TIMER -- DELAY N TICKS 





0057 

* 






0058 

★ * 

I I ME R TASK * 




0059 

★ 






0060 

★ 

TIMER TASK 

WILL have: Y UE ACIIv/ITY OOInG BEGIN 




0 0 61 

it 


:20 WORDS UF STACK SPALL, SYSTEM ALL' 




0062 

* 


16 POSSIBLE CONCURRENT EXECUTIONS 




0063 

it 



0 223 



0064 


fDB : A 

TMR TD,TI ME R,0,0, :2 0,0, 1 6 

0224 

0040 


0 064 + 




0225 

0228 


0064 + 




0226 

0 0 1 0 


0064 + 




0227 

0000 


0064 + 




0228 

0000 


0064 + 




0229 

0020 


0064 + 




02? A 

022F 


0 0 64 + 




0228 

0010 


0 064 + 




022C 

0000 


0064 + 




022E 

FOIE 


0064 + 







0065 

* 






0066 

* 

DELAYS N TICKS THEN TUGGLES CONSOLE WORD REGISTER HIT 




0067 

* 

BEGAN WITH 

Y= TA8LE ENTRY 




0068 

it 




0000022F 

0069 

TIMER 

EDO 

S 

0 22F 

1 A08 


0070 


R:ITIC 

ID(Y) INITIATE TIMER KEOUEST 

0230 

1002 

0002 

0 0 7 0 + 




0231 

DC46 

000b 

007 1 


IMS 

UELAYS(Y) HUMP DELAY COUNTER 

0232 

0 000 


0072 


NOP 


023 5 

FE 83 

0 2 37 

00 73 


JSK 

OUT TUGGLE CONSOLE WORD REGISTER oiT 

0234 

1 A 02 


0 07 4 


r:wait 

+SEMAURIY) WAIT FOR T I Mfc R TO EXPIRE 

0235 

5004 

0004 

0 0 7 4 + 




0236 

9E7 8 

022F 

0 0 7 5 


JMP 

TIMER REPEAT 




Figure F-l. RTX4 Demonstration Program, Page 6 of 13 



© 



PAGE 

0006 MAfkl) (Cl) 

K T X 4 

DEMO PROGRAM M). 1 

9 3410-1 0 t> 3 

1979/01/17 02: 

59539.50 

OUT 

— OUTPUTS 

TO CONSOLE 1'JOkU 

REGISTER 



0 0 7 7 

* 

CUMPLE MEN T 8 T Hh ADDRLSSfcl; 

i hi r 



0 07 8 

★ 

CALL t.O rtlTH Y= TABLE fc.Nl BY 



0 0 7 9 

* 





0 0 0 0 0 P 3 7 

0080 

no f 

EiJll 

$ 


OP 57 

C 0 4 7 0007 

0 0 81 


COPY 

BIT ( Y ) »U 

GET BIT Tu HIGGLE 

OP 38 

4t 31 

0082 


SHIFT 

0,1.0,4 

POST)ION TU K4 FIELD OF CH1 1 INSlR 

0239 

3 A 02 

0083 


R: a a IT 

CL)R 

REQUEST USE OF CONSOLE HURD KEG]Si 

OP 3 A 

0244 

0083 + 





023B 

0 1 0 4 

0 0 84 


IN 

COHOA:+CDR:,A 

READ CONSOLE AORO REGISTER 

0P3C 

4 30 A 

0 085 


XNX 

U 

INDEX CHIT INSTRUCTION a 1 ID BIT At 

OP 31) 

0 0 Of. 

0()8b 


CHIT 

0 , A 

COMPLEMENT ADDRESSED BIT 

0 2 31 

0404 

0 087 


St L P 

A , COWL) A • +COR : 

OIITPUI ID CONSOLt WORD REGISTER 

0P3F 

3 A 0 1 

0088 


R: 3 I g 

COR 

GIVE DP USE OF CONSOLE AURl) REGIS 

0240 

0 24 4 

0088 + 





opal 

2309 

0089 


KSK 


RETURN 



0 0 9 0 

★ 






0 0 9 1 

* * 

SEMAPHORE 

10 CONTROL CONSOLE aOhD REGISTER ACCtSS * 



0 0 92 

* 




0242 


0093 


SUB : A 

COR, t 


0 24 3 

0001 

0093 + 





0244 

0 0 01 

0093 + 





0245 

F03E 

0093 + 






00 04 

0 0 9 4 


LPOUL 



0246 







0247 







0248 







<‘249 











0 


1 j -* r' 





Figure F-i. RTX4 Demonstration Program, Page 7 of 13 


PAGE* U 0 0 7 MACHO (Cl) h'TX4 Dfc MO PROGRAM NO, 1 

197 9/01/17 02:59:41.00 TABLE -- T1 M K K TASK PARAMETERS 


93410-lU B3 


0 0 96 


024A 
0848 
024C 
024D 
G24E 
024F 
0250 
0251 
0252 
0253 
0254 
0255 
0256 
0257 
0258 
0259 
0 25 A 
0258 
0 25C 
0250 



0 097 

* THIS 

TABLE 

DtFJ.NES THE PAKAMA TERS FOR EACH ACTIVITY 


0098 

* 

OF THE 

TIMER TASK. 



0099 

* FORMAT IS: 




0100 

k 




00000000 

0101 

tdb 

EUU 

, 0 

TASK DESCRIPTOR BLOCK ADDRESS 

00 0 00 0 0 1 

0 102 

PHI 

too 

1 

PRIORITY TO BEGIN ACTIVITY AT 

00000002 

0103 

10 

EDO 

2 

ID TO USE IN TIMER REUUBS IS 

00000004 

0104 

SEMAOR 

EUU 

.4 

ADDRESS OF TICK REUUESi StMAPHOKI 

00000005 

0105 

TICKS 

EUU 

5 

NUMBER OF TICKS Tu KEUUEST 

00000006 

0106 

DELAYS 

EUU 

6 

NUMBER OF KEUUEST MADE SC* FAR BY 

00000007 

0107 

81 T 

EUU 

t 

BIT TO TOGGLE 


010 b 

* 





0 109 

* 





0110 

* 




0 0 0 0 0 2 4 A 

0111 

T ABLE 

EUU 

$ 


0224 

0112 


WORD 

TMKTU,:100,0, 

S3004,SEM3,4,0,3 


0100 
00 0 0 
30 04 
0 2 [) 8 
0 0 0 4 
000 0 
0003 
0223 
0100 
0 00 0 
2003 
0 204 
000 3 
0000 
0002 
0 22 3 
0100 
0 0 0 0 
GOOD 


0113 


0114 


WORD 


WORD 


IMKTD,J100,0,:2003,SEM2,3,0,2 


THRTD,:100,0,:cuoo,bEMC,:u,o,:C 


Figure F-l. RTX4 Demonstration Program, Page 8 of 13 


e 


PAPE 0008 MACRO (fj) W T V 9 OEMII PkOPwAM fjU. 1 
1979/01/1 1 02159142.00 iAHLE •> - 1 IM E R TASK PARAMETERS 


93910-10 m3 


0252 
025F 
026 0 
0 2b l 
0262 
0263 
0269 
0265 
0266 
0267 
0268 
0 269 
026 A 
026B 
026C 
0260 
026E 
0 26F 
0270 
027 1 
0272 
027 3 
0279 
0275 
0276 
0277 
0278 
0279 
027 A 
0276 
0 2 7 C 
0270 
0276 
027F 
0280 
023 1 


02FC 
00 00 
00 0 0 
OOOC 
0223 
0100 
0000 
6007 
0 2E9 
0007 
00 0 0 
0006 
0223 
0100 
OOoO 
EOOF 
0309 
0 0 OF 
0000 
0 0 0 E 
0223 
0100 
0000 
4005 
02DC 
00 05 
00 00 
0004 
0223 
010 0 
00 0 0 
3009 
02EC 
0 0 0 9 
00 0 0 
0 0 0 8 


0115 


WURO 


TMR11>, : 1 00,0, :6007 , SEMb, 7,0,6 


0116 


WORD 


Tmkid,: ioo,o,:Eo«F,stM£,: f,o, :fc 


0117 


WORD 


THRU), : 100, u , : 4t)0B, St M4,5,0,4 


0118 


roki! 


TMRTD, n 00,0, J 80 09,SEM8,9,0,3 


Figure F-*. RTX4 Demonstration Program, Page 9 of 13 


© 


© 

PAGE 0009 MACRO (Cl) KTX4 DEMO PidbKAM dl). 1 93410-10 0 3 

1979/01 /17 02:59:42.75 I AOLE -- TIMER TASK PARAMETERS 


0282 
0283 
0284 
0285 
0286 
0287 
0288 
0289 
028 A 
028H 
028C 
0280 
028E 
028F 
0290 
0291 
0292 
0293 
0 294 
0295 
0296 
0297 
0298 
0299 
029 A 
029B 
029C 
0290 
029E 
0 29F 
0 2 A 0 
02A 1 
02A2 
02 A3 
0 2 A 4 
02A5 


0223 
0100 
0 0 0 0 
0001 
02CC 
000 1 
0 0 0 ft 
0000 
022 3 
0100 
000 0 
90 0 A 
02F0 
0 0 0 A 
0 0 0 0 
0009 
022 3 
0100 
0000 
f 0 1 0 
0 308 
0010 
00 00 
00 OF 
0223 
0100 
0000 
1 0 0 8 
02E 8 
o o o a 
0 00 0 
0 0 07 
0223 
0 10 0 
0 0 0 0 
do of: 


0119 


0 120 


0121 


0122 


0 123 


rtURi) Trio TO,: l oo, u, : ooo i, SE mo, : l, u, o 


,vORI) TMNTO, : 1 0 0,0 , : 900 A , i>EM9 , : A , 0,9 


-VOKU TMRTl), : 1 00* 0 , IFOI 0 , SEMF , : 1 0,0 , :F 


WORD TMW 1L), : 100,0, :7 0<>8, StM7,B, U, 7 


h o k o tmkt n,:ioo,o,; oooe, bfcMo,:t,o, :d 



( 


Figure F-l. RTX4 Demonstration Program, Page 10 of 13 


PAGE 00 10 MACRO (Cl) RTX4 DEMO PROGRAM NU. 1 
1979/01/17 02:59:43.25 (ABLE -- TIMER TASK PARAMETERS 


9 3 <41 0 - 1 o a 3 


02A6 
02 A 7 
02A8 
02A9 
02A A 
02 AB 
0 2 AC 
02AD 
02AE 
02AF 
02B0 
02B 1 
0 2B2 
02B3 
02B4 
02B5 
0 2Bfc 
02B7 
02bft 
02B9 
0 2B A 
02BB 
02BC 
02B0 
0 2BE 
0 2BF 
02C0 
02C 1 
02C2 
02C3 
0 2C4 
02C5 
0 2C 6 
0 2C7 
0 2 C. ft 
0 2 C 9 


0 3 0 0 
OOOE 
0000 
0 0 0 D 
0223 
0100 
0000 
AOOB 
02F 4 
0 0 OB 
0 0 0 0 
000 A 
0223 
0 1 0 0 
0000 
50 06 
O2E0 
0 0 06 
0000 
0005 
0223 
0100 
0000 
BOOC 
02F8 
OOOC 
00 0 0 
0 0 0 B 
022 3 
0100 
0 0 0 0 
1002 
021)0 
0 0 0 2 
0 0 0 0 
0 0 01 


0 124 


vVORU 


T mr in,:ioo,o,: auob,sema,:8,o,:a 


0 1 25 


rtUR D 


TMWTD, :l00,0,:5006,SEM5,6,0,5 


0 126 


WORD 


Tmr rD,: ioo,o,: bool*, semb, :c, o ,:b 


0 1 27 


i/YDR!) 


Ti-i r rn,: i oo, o,: 1002 , semi , 2 , u, 1 


Figure F-1. RTX4 Demonstration Program, Page 11 of 13 



© 

PAGE 0011 MACPU (Cl) IUx<4 Db.MU PHOGkAM fit!. 1 
1979/01 /1 7 02:59:40.00 TIfiEK SEMAPHORES 


02CA 


0 1 29 

SDH : A 

s t m o , o 

02CH 

0000 

0129 + 



0 2CC 

0 0 0 0 

0 129 + 



02CD 

F 0 36 

0129 + 



02C6 


0 1 30 

SDH : A 

s t: m i , u 

0 2CF 

0 0 00 

01 30 + 



0 21) 0 

0 0 0 0 

01 3u + 



0 2D 1 

F 0 36 

0 13 0 + 



0 2 D 2 


0 131 

5 D b : A 

SbM2,0 

02D 3 

00 00 

0131 + 



02D4 

0 0 0 0 

0131 + 



02D5 

F0 3E 

0 131 + 



02D6 


0132 

SDH : A 

S6M 5,0 

0 2D 7 

0000 

01 32 + 



0 208 

0 0 0 0 

0132 + 



02D9 

fo3f: 

0 l 32 + 



0 21) A 


0 1 33 

S D b : A 

StM4,0 

02DB 

0 0 0 0 

0133 + 



02DC 

0 0 00 

0 13 3 + 



02DD 

F 0 36 

0133 + 



02DE 


0134 

SDH : A 

S 6 M 5,0 

0 2DF 

0000 

013 4 + 



0 2E0 

0000 

01 54 + 



02E 1 

F03E 

0134 + 



0262 


01 55 

SDb : A 

SEMb, 0 

0263 

0000 

0155 + 



0260 

0000 

01 55 + 



0265 

FO 36 

0 155 + 



0266 


01 5b 

SDH : A 

SE.M7 • U 

02E7 

0 000 

0 l 3 b + 



0268 

0 0 0 0 

0156 + 



0269 

F0 3F; 

013b + 



02EA 


015 ! 

SDH : A 

St MM , 1) 

0268 

0 0 0 o 

0 1 57 + 



026C 

0 0 0 0 

015 7 + 



0 260 

F 0 31 

0 1 37 + 






Figure F-l. RTX4 Demonstration Program, Page 12 of 13 


1 





© 


PAGF 0012 MACliU (Cl) F|X9 U F M 0 PkOGKAM l\fU. 1 93910-lu F> 3 

1979/01/17 02:59196.00 TlMtk SfcMAPHOrtF S 


02EE 


01 38 

SUB : A 

8 fc M 9,0 

0 2EF 

0 0 0 0 

0138 + 



0 2F0 

00 00 

0138 + 



02F1 

FO'SE 

0 l 38 + 



02F2 


0139 

SUB :-A 

SF MA,I) 

02F3 

0000 

0 1 59 + 



0 2F 9 

0000 

0 1 39 + 



02F5 

F03E 

0 1 39 + 



0 2F6 


0190 

SUB : A 

SFMB , 0 

0 2F7 

00 0 0 

0 1 9 0 + 



02F8 

00 00 

019 0 + 



Q2F9 

F0 3E 

019 0 + 



02F A 


0191 

SUB: a 

St MC , 0 

02FB 

0000 

0191 + 



02FC 

0000 

0191 + 



0 2 F 0 

F0 3E 

019 1 + 



0 2FE 


0192 

SOB : A 

StMD, 0 

0 2FF 

0 0 0 0 

0 19 2 + 



UiOO 

0000 

0192 + 



0301 

F 0 3 F 

0192 + 



0302 


0193 

sob: a 

SEME , 0 

0303 

0000 

0193 + 



o 

o 

0000 

0 ! 9 3 + 



0305 

FOSE 

0 193 + 



0306 


0 1 99 

S U h : A 

SF MF , 0 

0 30 7 

0 0 0 0 

0 199 + 



0 308 

0 0 0 0 

0 19 9 + 



0 309 

FOSE 

0 19 9 + 






Figure F-l. RTX4 Demonstration Program, Page 13 of 13 



PAGE 0013 MACKU (Cl) R T X 4 DEMO PROGRAM Uli. 1 43410-10 t >3 

1479/01/17 02:59:47.25 ENVIRONMENT 1NEURM A T 1 UN 


0 30 A 

0 50H 0000 
0 30C 030A 
0300 0001 
030E 0000 
0310 0000 
0311 0000 
0312 0000 
0313 0000 
0314 0000 
0515 F06E 
0316 0010 
0317 0030 
0316 0000 
0 31 A 0 0 00 
0 32A 0000 
032B 0000 
052C 0000 
032D 0000 
032E 0000 
0 52F 7FFF 
0330 
0 331 
0332 

0333 0000 


0146 * 

0147 * oleine environment conirol block 

0 1 4 H * 

ot49 ecu: a ecui,o 

0 149 + 

0 14 9 + 

0 1 49 + 

0149 + 

0 14 9 + 

0149 + 

0149 + 

014 9 + 

0149 + 

0149 + 

0149 + 

0 1 49 + 

0149 + 

014 9 + 

0 1 49 + 

0149 + 

0 1 49 + 

0 149 + 

0149 + 

014 9 + 

0 149 + 

0149 + 

014 9 + 

0 14 9 + 

0150 l NO 


0000 ERRORS 
0000 WARNINGS 


( 0 0 0 0 ) 
( 0000 ) 



Figure F-2. Memory Map of Linked RTX4 Demonstration Program* Page 



PAGE l 

/ 9 / 0 1 / 1 / l) 3 I 0 0 I 0 4 

LINK (A 4) 



SO FILE 

= K1X0EMO 

H IN 



bl FILE 

= RlXOEMO 

OBJ 



SA FILM'S) 

- R T X 

L IH 



bl A TIJS 

= relocatable 





WITHIN MEMORY LIMI1S 




UNRESOLVED 

SF. COnOAk IE S 



LOAD OFFSET 

= 0100 




TRANSFER At)0PF.SS 

= 0 4 5B 




MAIN MEMORY LIMITS 

= OOOO-FFFF 




(ABSOLUTE SYMBOLS) 





OObb....kJCNlK 

0 U6H....RICNSM 

OUbA..*.R:WLKb 

OObC . . . 

.RlPFLG 

0061). . , . K I PFK 

0 0 6 E....RISREG 

OObp * . # # K 5 S I'*! S W 

0 u7 0 . . . 

,R I CORG 

0071....RIB TCI 

0072....RIMPM1 

0073....RIMPM2 

0 U 7 E . . . 

.RIFATL 

007F.,..R:FAT1 

0 0 80 .... K1X: 




(REL AkEA 1) BLANK (0100-134FR 

- RAM) 



0100....RIInIT 

0 100. . ..RILOW 

0 4 3B . (M)DEBUG4 

OHSF ... 

.RI TOOK 

0HT>9 ....RJODOR 

oboe....r:sekb 

ObFC. ...KlStKL 

0 B F 0 . . , 

.R JOG IN 

0C20 .., .r:begi 

0CH4 ... .RIENO 

OCEh. .. .RIPRIO 

0 C E 2 . .. 

. R I I S I G 

OCF 2 ... .KISIG 

OCFB.. . .RiSbIG 

0012. . . .R! IwAI 

0012.. . 

. R I W A 1 T 

001 A ... .K ISWA I 

004 1 ... .RI ITIC 

004 3. .. .RI TIC I 

0099... 

.RI1ICP 

0 D C 0 .. . .KILTIC 

0000. .. .RIKTIC 

000/ ....RlTKAC 

ODE 3. . . 

. R I C T IC 

OE12....KIMTIC 

OE 20 . ...RlR'WAL 

ObbC . . . . k I A'L AC 

U E A 9 . . . 

. T T L F 41 

OFBO. . . .RISTOU 

OEBrt. ... RIGJ 00 

0EC0....RIAWAL 

0 EOF.. . 

. R I 1 W A L 

OF 29 . . . .RICWAL 

0 F so _ STUF : 

OF bh. . . . RIGPR1 

0 F b 2 . , . 

.RIGPR 

OF 66, ... RISPK I 

OF 7 A ... .KIC!N T 

OF 94. .. .RICNbl 

OFAb... 

.KlbEND 

0FB4 . . ISNl) 

OF DC ... .KIRECV 

OF FE . . . .K I IRCV 

1023. .. 

. K I G F 1 M 

104B, ...KIG1VM 

1 OHO .... RIAriUE 

1 Orth .. . . R:khuF 

1097... 

. R I RE 1 2 

1097 . ...GIZ 

U) 4 A .... K I 0 A U X 

109E ... .RIDA 

1 0 A 2 . . . 

.RIO ISP 

1006..,.RibACT 

10Dt...,KIlACO 

i!Ort....RILblK 

11 4 6 . . . 

.R IKS 1 K 

114ft....KISTRT 

1 1 b b . . . . K I I N f l 

1i7 b .. . . k IPaKE 

1196... 

. R I 6 T S 

11 A1 ... .KIGVST 

I1 Ah ... .RIGVSH 

11 t» 4 . . . . R I P A u b 

11 CO.. . 

.RIAE TH 

1104... . k I CNTH 

1 100 . . . .KJiiSTH 

> u;ar.„ , ■ RiHicTh 

1 IE 9. . . 

. R I U I T H 








Figure F-2. Memory Map of Linked RTX4 Demonstration Program, Page 2 of 2 



1 


11EH....r:uIRTim 

1 IFfc . 

...KJUS1REX 

1213....RSSFfH 

1 22£ . .. 

. R : S ( K 0 E X 

1230....KSOOOREX 

12 31 . 

. . . R : K 1 X E X 

12-U ... ,k: xp i t 

124 2... 

. R : 1 A B L 

124 7 ..,.R:SYSX 

12bF . 

. . . R £ I N I t 

125F.(M)RSklNT 

12 Ah... 

. R: S E C U 

12H3. . , . R : (\/ECb 

1 2Hb . 

. . .KS.DECH 

12U7....K:0 f H K 

12C A . . . 

. 1:1N11 

12CA.,..R:iJlNI 

i 2CE . 

. . . K I F Ml j|. 

l 2CF . . « . R S P A fC 

12b A , . . 

. K I G 0 P F 


1 i50*. # # r:high 


********* *********************** 


MISSING 

= GJ4 

G : E 

F:MONT 


G: v 

G:u 

g:l 


g:s 

g : g 

I : 10 


G : x 

G : l 

g : b 


g:s 

F SCREA 

G: n 


RJSATD 

G : H 

FSCFNO 


G : 1 

g: 3 

G: D 


G:ti 

g:p 

RIGA It) 


K:DMt'J1 

GS K 

Gib 


G : F 

G: w 

G : 0 


g : a 

F:DELE 

G • R 


GSM 

G: 7 

g:h 


g: y 

G • 2 

G: C 


g: 1 

G:o 

G IS 


F S CONN 

g: j 









ComputerAutomation - 


APPENDIX G 
RTX4 MACRO SUMMARY 


Pa^e 


4-3 

BGIN:A 

arg,tdb,prdesc 




where: arg 

Must match the argument specified in the 
R:BGIN macro. 



tdb 

Address of the Task Descriptor Block as 
specified in the FDB:A macro. 



prdesc 

Priority descriptor defining the task's 
priority. 



This macro generates an argument list for an R:BGIN macro 

5-6 

ECB: A 

label,uat 




where: label 

Label to be assigned to the start of the 
Environment Control Block; referenced u> 
the INIT:A macro. 



uat 

Address of the Unit Assignment Table. 



This macro generates the Environment Control Block. Must 
immediately precede the END statement of the last user's 
program module. 

5-1 

INIT:A 

a>q»x,y,ecb,tdb,pri,amtfree,adrfree,topmem 



where: E>E>x>,X 

Initial values of the A, Q, X, and Y 
registers for initial user's task. 



ecb 

Address of the Environment Control Block. 



tdb 

Address of the Task Descriptor Block for 
initial user's task. 



Ell 

Activity priority for initial user's task 



amtfree 

Amount of freepool space in words 
(optional). 



adrfree 

Address of the freepool (optional). 



topmem 

Upper limit of memory available to RTX4 
(optional). 



T his macro 

:■ the Initialization Block 



m 
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Page 

8-4 



8-3 


5-7 


7-8 



4-3 


4-4 


MAIL:A arg , mai1 



where: 

arg 

Must match the argument of an R:$END 
macro or R:RECV macro. 



mail 

Label of the appropriate mailbox as 
defined by the MDB:A macro. 


This macro generates an argument list for an R:S£ND macro 
or R:RECV macro. 

MDB: A 

mail 




where: 

mai 1 

Identifier to be assigned to the 
mailbox. 


This macro defines 

a mailbox facility. 

R:ABUF 

amount 




where: 

amount 

Number of words to be allocated. 


This macro submits a request for the system buffer 
allocation service. This service allocates a buffer 
for the program's use. 

R: AWAL 

arq 




where: 

arg 

M4D12 pointer to the argument list, 
generated via the WALL:A macro. 


This macro submits a request for the system wall clock 
absolute timer service. This service initiates a timer to 
cause a semaphore to be signalled at an absolute wall clock 
time. 

R:BGIN 

arq 




where: 

arg 

M4D12 pointer to the argument list, 
generated via the BGIN:A macro 


This macro submits a request for the system task-processing 
service. This service initiates task execution; i.e., it 
creates an activity. 


R:CINT 


This macro submits a request for the system console 
interrupt control service. This service causes the 
activity to return if the console interrupt is pressed. 
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Page 

7-4 R:CTIC arg 

where: arg M4D12 pointer to the argument list 

generated by the TICK:A macro. 

This macro submits a request for the system tick clock 
timer request cancellation service. This service cancels 
a previous R:ITIC request. 

7-9 R:CWAL arg 

where: arg M4D12 pointer to the argument list, 

generated via the WALL:A macro. 

This macro submits a request for the system wall clock 
timer request cancellation service. This service cancels 
a previous R:IWAL or R:AWAL request. 

4-3 R:END 

This macro submits a request for the system activity 
termination service. This service terminates the activity- 
requesting the service. 

7-7 R:GATD 

This macro submits a request for the system time and date 
access service. This service reads the time and date in 
ASCII. 

4-4 RrGPRI 


This macro submits a request for the system activity 
priority access service. This service returns the calling 
activity's priority in the A register. 


7-7 R:GTOD 


This macro submits a request for the system time of day 
access service. This service returns the time of day in 
the AQ register pair. 

7-3 R:ITIC arg 

where: arg M4D12 pointer to the argument list, 

~ generated via the TICK: A macro. 

This macro submits a request for the system tick clock timer service. 
This service initiates a timer to cause a semaphore to be signalled 
after a specified number of ticks of the Real-Time Clock. 
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7-8 


7-3 


7-5 


5-7 


8-4 


R:IWAL arg 

where: arg M4D12 pointer to the argument list, 

generated via the WALL:A macro. 

This macro generates a request for the system wall clock 
interval timer service. This service initiates a timer to 
cause a semaphore to be signalled after a specified time 
interval has elapsed. 

R:M T IC arg 

where: arg M4D12 pointer to the argument list, 

generated via the TICK:A macro. 

This macro submits a request for the system tick clock timer 
request modification service. This service modifies a 
previous R:ITIC request. 

R:PAUS prdesc 

where: prdesc Priority descriptor. 

This macro submits a request for the system round robin 
scheduling service. This service removes the first activity 
of a given priority from the ready list and reenters that 
activity into the ready list. 

R:RBUF address 

where: address Address of the buffer to be released. 

This macro submits a request for the system buffer release 
service. This service releases space previously allocated 
for a specified buffer. 

R:RECV arg 

where: arg M4D12 pointer to the argument list, 

generated via the MAIL:A macro. 

This macro submits a request for the system message receipt 
service. This service receives a message from a specified 
mailbox. 



! 


H 

| 



-m 
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3-10 


R:SATD 


8-4 


R:SEND 


arq 

where: 


arq Address of argument block...a sevenword 

block containing date and time values in 
the order: year, month, day, hour, 
minute, second, and hundredths of a 
second. 


This macro submits a request for the system date and time 
definition service. This service sets the date and time in 
ASCII. 


arq 

where: 


arq M4D12 pointer to the argument list, 

generated via the MAIL:A macro. 


This macro submits a request for the system message trans¬ 
mission service. This service sends a message to a specified 
mailbox. 


6-7 


I 4-4 

C 

- i 

i 7-7 


R:SIG sema4 

where: sema4 Address of the Semaphore Definition 

Block to be signalled. 

This macro submits a request for the system semaphore signal 
service. This service causes a specified semaphore to b 
signalled. 

R:SPRI prdesc 

where: prdesc Priority descriptor. 

This macro submits a request for the system activity priority 
definition service. This service alters the calling activity's 
priority according to the supplied priority descriptor. 

R-STOD 


This macro submits a request for the system time of day 
definition service. This service sets the time of day to 
the value specified in the AQ register pair. 

6-7 R:WAIT sema4 


where: sema4 Address of the Semaphore Descriptor 

Block to wait on. 

This mac^o submits a request for the system semaphore wait 
service. This service causes the activity to wait on a 
specified semaphore. 
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Page 

6-5 


7-3 

7-4 



3-7 


SDB:A label . value 

where: 1abel Address label of the semaphore. 

value Initial value of the semaphore. 

This macro generates a Semaphore Definition Block. 

TICK:A arg t id, sema4 , count 

where: arg Must match the argument of an R:ITIC, 

R:MTIC, or R:CTIC macro. 

Identifier of a tick clock timer. 


sema4 Address of the semaphore to be signalled 
(R:ITIC or R:MTIC), or dummy argument 
with any defined value (R.CTIC). 

count Number of ticks that must elapse before 
the semaphore is signalled (R:ITIC or 
R.MTIC), or dummy argument with any 
defined value (R:CTIC). 


This macro generates an argument list for an RrXTIC, R:MTiC 
or R:CTIC macro. 

TDB: A • label, s tart, y scratch,stackad,stackamt, flags .usage 


« 


where: label Label to be assigned to start of TDB. 

start Starting address of task. 

yscratch Amount of Y-scratchpad to be used by the 
task. If zero, the Y register of the 
calling task is used. Usually is zero 
(or omitted) for a serial task. 


stackad Address of preallocated stack. If zero, 
stack space is allocated by RTX4. Must 
be zero (or omitted) for a reentrant 
task. 


stackamt Amount of stack space used by the task. 

flags None currently defined. (Optional.) 

usage Maximum number of concurrent activities 

of this task. (Optional.) 


This macro generates a Task Descriptor Block. 
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7-8 

7-9 


WALL:A arg , i d , sema4 , upper ,1 ower 


where: 


arg 


i d 

sema4 


upper 


lower 


Must match the argument specified in an 
R:AWAL, R:IWAL, R:CWAL macro. 

Identifier of a wall clock timer. 

Address of the semaphore to be signalled 
(R:AWAL or R:IWAL), or dummy argument 
with any defined value (R:CWAL). 

Upper word of the 32-bit integer 
specifying the number of wall clock 
intervals that must elapse before the 
semaphore is signalled (R:AWAL or R:IWAL), 
or dummy argument with anv defined value 
(R:CWAL). 

Lower word of the 32-bit integer specify¬ 
ing the number of wall cIock intervals 
that must elapse before the semaphore : 
signalled (R:AWAL or R:IWAL), or dummy 
argument with any defined value (R:Cldu 


This macro generates an argument list for an R:AWAL, R:IWAi 
or R:CWAL request. 
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APPENDIX H 
MACRO FILE CONTENTS 


The RTX4 user accesses macro definitions, table definitions, or other code 
via certain macro files. These macro files and their contents are listed below. 

GEN.MAC (General Macro File) 


• Macro definitions: 

EXCH:M 
COPY:M 

• Fixed memory address assignments 

• Non-printing ASCII characters 

• S register bit definitions 

• SYMATT directive bit definitions 

• Hardware stack definitions 

• Distributed I/O device and interrupt addresses 

RTX.MAC (RTX4 User Macro File) 


• Macro definitions 
INIT:A 
SINGL:- 
TDB: A 
ECB: A 
EDXVT:A 
SDB: A 
MDB: A 
BGIN:A 
TICK:A 
MAIL:A 
WALL:A 
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RTXD.MAC (RTX4 Development Macro File) 

• Macro definitions 

PUSH: 

POP: 

COPY: 

EXCH: 

ASTAR: 

RSTAK: 

CHK: 

SYS: A 

• Table definitions 

TDB - Task Descriptor Block 

ACB - Activity Control Block 

ECB - Environment Control Block 

EDB - Environment Descriptor Block 

CCB - Clock Control Block 

SDB - Semaphore Descriptor Block 

INIT - RTX Initialization Block 

• RTX exception codes 

• RTX block check values 

• RTX base page definition 

• Environment memory pool definition 

• Miscellaneous RTX system equates 

IQS.MAC (I0S4 User's Macro File) 


• Macro definitions 

BUF: R 
IOB: A 
UAT:AA 
UAT:EE 
UAT :11 

• Table definitions 

IOB - Input/Output Block 

• Operation, position, and function codes 

• Error codes 

• Status codes 
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IOSD.MAC (I0S4 Development Macro File) 

• Macro definitions 

PATCH: 

I: EOB 
CIB:DM 
CIB:DH 
DIB:DM 
DIB:DH 
DIB:LP 
DIB:ST 

• Table definitions 

CIB - Controller Information Block 
DIB - Device Information Block 
TIB - Temporary Information Block 

• Distributed I/O equates 

• I/O error block definitions 

SFM.MAC (SFM User's Macro File) 

• Macro definitions 

CONN:A 
DELE:A 
CREA:A 
MONT:A 
FCB:SA 

• Table definitions 

FCB - File Control Block 
FDB - File Descriptor Block 

• Parameter list equates 

SFMD.MAC (SFM Development Macro File) 

• Table definitions 

VCB - Volume Control Block 

• F list entry definition 

• Buffer control and flag word definitions 
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NOTES ON ITEMS ISSUED WITH RTX4 (Cl) 


1. RTX User's Manual (CO) 

* 

Appendix H describes the macro files (supplied with OS4 and RTX4 and their 
contents. The contents described for GEN .MAC should include all RTX4/ 
IOS4/SFM service call macros. 

2. IOS4 User's Manual (CO) 

2.1 Similar comment as given in 1, except that it is Appendix G. Also 
page 8. 1 refers to Appendix I instead of G and the Contents List has. 
omitted the Appendix altogether. 

2.2 Appendix B 

The Introduction B. 1 should include reference to the Volume Control 
Block and FUST described later in the Appendix. 

3. IOS4 (Cl) 

3.1 The IOS.HLP 

This file includes description of the IOSDEMO program files. This 
demo is now cal led SFMDEMO . 

3.2 The Line Printer DIB (Standard) 

This is configured for 80 characters per line and 57 lines per page. 
The DIB:LP macro also defaults to these values and not 133 and 39 as 
described. 

3.3 IOSD.MAC 


Note that this file equates the CRT DIO channel address to 2 instead 
of 4 as one might expect. 



Com piiterAutomatiori- 


NOTES ON ITEMS ISSUED WITH RTX4 (Cl) (Cent.) 


3.4 Write Direct Stream I/O 

There is a fault connected with this. If a program attemps to do 
Write Direct Stream to a file in order to overwrite the exact number 
of bytes remaining in the file, SFM ignores the request and indicates 
an end of a block error (:4E). This fault may be overcome by 
patching as follows: 

Location Old Contents New Contents 


F:CEOF+:A : 9E82 . :0000 

The address of F:CEOF may be determined by examining the link-map 
produced by linking the user program with RTX/IOS/SFM. 

3.5 TV/ TK/TY End-of-lnput Action 


Currently, when carriage-return is required to terminate an input I/O 
request, IOS4 responds by repeating just that character, which means 
that it is possible for subsequent output to overprint the previously 
typed line. (In the case of OS4 message output, no overprinting 
occurs because a line-feed is output first, before the message.) 

To ensure that no overprinting occurs, users may modify the location 
identified on link maps by the symbol TV EL!:. Normally this 
location contains 1, but 2 should be put in its place to ensure that 
carriage-return is followed by a line-feed after every input line is 
terminated. 


4. RTX (Cl ) 

4.1 The fault described in connection with the previous version of RTX4 
namely R:IWAL still exists and the same patch applies. For the 
benefit of those users new to RTX4, a copy of the EN issued just 
before this Cl release is attached to these notes. 
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-^^^Com puter Automation— 


NOTES ON ITEMS ISSUED WITH RTX4 (Cl) (Cont.) 


4.2 R:PAUS 

This service should allow an activity to de-schedule itself so that 
it is placed at the end of the queued activities of the same prioity 
as itself. However, R:PAUS de-schedules the next activity in the 
queue. The following patch cures the fault: 



Location 

O Id Contents 

N ew Contents 


R:PAUS+:8 

:A022 

:2922 

4.3 

MAILBOX 




MDB:A macro is wrong. It allocates word containing 0 for Mailbox 
Usage Semaphore and it should contain 1 . 


Change source line 319 from "Word 0 - Mailbox Usage Semaphore" 
to "Word 1 - Mailbox Usage Semaphore". 

4.4 RTX MACROS 

TICK:A, WALL:A, MAIL:A,SDB:A,MDB:A Macros contain invalid 
constructions for testing n umber of parameters supplied with the call, 
e.g. (X#?<3. j 

| 

There are no simple, changes that can be made and users are advised 
to ensure that they brovide the correct number of parameters since 
the macro definitions dcj not check correctly. 


CAI Limited 

European Technical Support Group March, 1979 
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ENGINEERING 

NOTICE 


DOCUMENT NO. 

REV. 

TITLE 

INCORP. 

DATE 

IS 

WAS 

W034IO-XX 

81 

3 1 

R T X4 - R:IWA L 






































■'ACTIVITY NOTES: 


NU 


fh 


7 . I ,<o, 9 lS 


TYPE 


AEN 

STOP ORDER 
DEVIATION 
RELEASE 
STANDARD 


□ 

□ 

□ 

K 


CLASS 


A-MAND/FUNC X. 

B-NON-MAND/FUNC □ 

C-RECORD CHG □ 


AFFECTED ITEMS 


REA NO. 0444 7 


CO-ORC WITH: 


REASON FOR CHANGE: 

CERTAIN COMBINATIONS OP 
R- TOOL AND USER-SPECIFIED 
INTERVAL VALUES PRODUCE 
INCORRECT SHORT TIME 
INTERVALS BECAUSE THE CODE ASSUMES 
THAT THE ADD INSTRUCTION AFFECTS 
THE CARRY STATUS BIT,WHICH IT DOESN’T 


INSCRIPTION OF CHANGE: 

A. PATCH AS FOLLOWS : 
LOCATION OLDCONTENTS 


+ • 22 

: CS44 

+ : 23 

: C433 

+ :24 

•‘68 43 

+•‘25 

:5CC 1 

+ *2(o 

:0B0l 

+: 2T 

•‘8482. 

+.*28 

:3E30 


NEW CONTENTS 


•’0E07 RBIT 0 ,S 

• 4712J 
•0004) 

• C4B3 COP/ Q,CC-‘TL (X) 
•‘0712.) 

•‘0003) 

•*8432.COPY A,cc--Tum 


ADDC TL (Y),Q 


ADDCJTU (Y), A 


HARDWARE CHG. 

PlRIM. 

□ 

SFC. 

□ 

SOFTWARE CHG. 

K 

□ 

PIJBL. CHG. 

□ 

□ 

CAPABLE CHG. 

□ 

□ 

DOC. CHG. 

□ 

□ 

CONFIGURATIONS 

i □ 

□ 

PROCEDURES j 

□ 

□ 

TOOLING 

□ 

t -1 

1_l 

TEST EQUIP. 

n 

_q_ 


EFFECTiVifY 


ACTIVITY 


NOTIFY VEND 


IN STOCK 


/I 


KITTING 


ASSEMBLY S 


/ 


TOUCH U 


IPT 


FliTGOODS 


>el)ST. RET. 


2 


u IP4SI p l 


P.EWK TEST REG’D 


(NOTE: JMP POST AT R:IV/AL +.*28 IS REDUNDANT 
BECAUSE POST IS THE NEXT LOCATION.) 


CONTINUITY 

G 

CABLE SC \N 

□ 

CAPABLE 

□ 

MEMORY 

□ 

CARD 

■ • □ 

FINAL 

□ 

NO TEST REQ’D 


APPROVALS 

ENGR. 


SOFTWARE 

. ^tddL _j 

O. A. 

C | 

CAP. TEST i 

GE5TT7 i 

MASTSCHED 

'£ZLi isl 1 

MATERIALS j 


TEST ENGR. i 

•_ 1 

TECH SERV 


Fcustserv 


M F G. ENGR 

~ - w" 

i PUBLICATIONS 


1 DR. BY: A. DUZICR ,2.1 

CHKD. 

c ;'Z- c 

i REL. BY: A 

^ A ^ 

i DATE: |.i 
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